TCO Tracing Policy gRPC API

This tutorial demonstrates how to use our TCO Tracing gPRC API to define, query, and manage your TCO policy criteria, used both for spans and logs.

View this page to learn how to use our TCO Optimizer HTTP API to define, query, and manage your TCO policy overrides, used exclusively for logs.

Overview

Tracing policies aim to match spans, which are the fundamental components of a trace. The matching process is carried out based on the rules you define. Those rules can be defined using application/subsystem/operation/service names or by tag names and values. There are various types of matching rules, explained in detail below.

Matching process

Spans that match all rules in a policy will be assigned the priority level defined in that policy.

Every rule targets a property (e.g. Application) by RuleTypeId.

TagRule targets a tag name and a tag value (e.g. tag name: tags.http.method and tag value: GET).

Examples:

• A rule on Application with the RuleTypeId RULE_TYPE_ID_IS and the name default,app1 will match all spans with application name default or app1.

• A rule on Subsystem with RuleTypeId RULE_TYPE_ID_START_WITH and the name authSer will match all spans with subsystem names that start with authSer.

• A TagRule with the name tags.http.target, RuleTypeId RULE_TYPE_ID_INCLUDES, and the value /api will match all spans that have the tag tags.http.target and a value that contains /api.

How to Send gRPC requests

STEP 1. Install grpcurl.

STEP 2. To use this API you need to create a personal or team API key. It’s recommended to use permission presets, as they are automatically updated with all relevant permissions. Alternatively, you can manually add individual permissions.

Preset	Action	Description
TCOPolicies	LOGS.TCO:READPOLICIES LOGS.TCO:UPDATEPOLICIES SPANS.TCO:READPOLICIES SPANS.TCO:UPDATEPOLICIES METRICS.TCO:READPOLICIES METRICS.TCO:UPDATEPOLICIES	View Logs TCO Policies Manage Logs TCO Policies View Tracing TCO Policies Manage Tracing TCO Policies View Metrics TCO Policies Manage Metrics TCO Policies

STEP 3. Run grpcurl with this template:

grpcurl -H "Authorization: <cx_api_key>" -d "<data_json_object>" <host_name> <grpc_method>

You can find the Management host_name here, depending on your Coralogix domain and region.

Supported API calls

The API supports the following gRPCs:

• Get Policy

• Create Policy

• Update Policy

• Get Company Policies

• Delete Policy

• Reorder Policies

• Toggle Policy

Notes:

• This API supports both log and tracing policies.

• In some requests, the field source_type_rules appears, containing unique fields for each. The field source_type may also appear, allowing you to decide which type of policies you want to receive or affect.

The API supports the following gRPCs:

API calls

rpc GetPolicy(GetPolicyRequest) returns (GetPolicyResponse)

GetPolicyRequest

message GetPolicyRequest {
  google.protobuf.StringValue id = 1;
}

GetPolicyResponse

message GetPolicyResponse {
  Policy policy = 1;
}

Example

grpcurl -H "Authorization: <cx_api_key>" -d '{
  "id": "abcd"
}' ng-api-grpc.:443 com.coralogix.quota.v1.PoliciesService.GetPolicy

rpc CreatePolicy(CreatePolicyRequest) returns (CreatePolicyResponse)

CreatePolicyRequest

message CreatePolicyRequest {
  google.protobuf.StringValue name = 1;
  google.protobuf.StringValue description = 2;
  Priority priority = 3;
  optional Rule application_rule = 4;
  optional Rule subsystem_rule = 5;
  optional ArchiveRetention archive_retention = 6;
  oneof source_type_rules {
    LogRules log_rules = 7;
    SpanRules span_rules = 8;
  };
}

CreatePolicyResponse

message CreatePolicyResponse {
  Policy policy = 1;
}

Example

grpcurl -H "Authorization: <cx_api_key>" -d '{
  "name": "policy name",
  "priority": "PRIORITY_TYPE_HIGH",
  "applicationRule": {
    "ruleTypeId": "RULE_TYPE_ID_START_WITH",
    "name": "sdasdazxczxca"
  },
  "archiveRetention": {
    "id": "abcdid"
  },
  "spanRules": {
    "tagRules": [],
    "serviceRule": {
      "ruleTypeId": "RULE_TYPE_ID_IS",
      "name": "asdas"
    }
  }
}' ng-api-grpc.:443 com.coralogix.quota.v1.PoliciesService.CreatePolicy

rpc UpdatePolicy(UpdatePolicyRequest) returns (UpdatePolicyResponse)

UpdatePolicyRequest

message UpdatePolicyRequest {
  google.protobuf.StringValue id = 1;
  google.protobuf.StringValue name = 2;
  google.protobuf.StringValue description = 3;
  Priority priority = 4;
  optional Rule application_rule = 5;
  optional Rule subsystem_rule = 6;
  optional ArchiveRetention archive_retention = 7;
  oneof source_type_rules {
    LogRules log_rules = 8;
    SpanRules span_rules = 9;
  };
}

UpdatePolicyResponse

message UpdatePolicyResponse {
  Policy policy = 1;
}

Example

grpcurl -H "Authorization: <cx_api_key>" -d '{
  "id": "asdf",
  "name": "same name",
  "priority": "PRIORITY_TYPE_MEDIUM",
  "logRules": {
    "severities": [
      "SEVERITY_VERBOSE",
      "SEVERITY_WARNING"
    ]
  }
}' ng-api-grpc.:443 com.coralogix.quota.v1.PoliciesService.UpdatePolicy

rpc GetCompanyPolicies(GetCompanyPoliciesRequest) returns (GetCompanyPoliciesResponse)

GetCompanyPoliciesRequest

message GetCompanyPoliciesRequest {
  google.protobuf.BoolValue enabled_only = 1;
  optional SourceType source_type = 2;
}

GetCompanyPoliciesResponse

message GetCompanyPoliciesResponse {
  repeated Policy policies = 1;
}

Example

grpcurl -H "Authorization: <cx_api_key>" -d '{
  "sourceType": "SOURCE_TYPE_SPANS",
  "enabledOnly": true
}' ng-api-grpc.:443 com.coralogix.quota.v1.PoliciesService.GetCompanyPolicies

rpc DeletePolicy(DeletePolicyRequest) returns (DeletePolicyResponse)

DeletePolicyRequest

message DeletePolicyRequest {
  google.protobuf.StringValue id = 1;
}

DeletePolicyResponse

message DeletePolicyResponse {
  google.protobuf.StringValue id = 1;
}

Example

grpcurl -H "Authorization: <cx_api_key>" -d '{
  "id": "abcdid"
}' ng-api-grpc.:443 com.coralogix.quota.v1.PoliciesService.DeletePolicy

rpc ReorderPolicies(ReorderPoliciesRequest) returns (ReorderPoliciesResponse)

ReorderPoliciesRequest

message ReorderPoliciesRequest {
  repeated PolicyOrder orders = 1;
  SourceType source_type = 2;
}

ReorderPoliciesResponse

message ReorderPoliciesResponse {
  repeated PolicyOrder orders = 1;
}

Example

grpcurl -H "Authorization: <cx_api_key>" -d '{
  "orders": [
    {
      "order": 0,
      "id": "abcd1"
    },
    {
      "order": 1,
      "id": "abcd2"
    }
  ],
  "sourceType": "SOURCE_TYPE_LOGS"
}' ng-api-grpc.:443 com.coralogix.quota.v1.PoliciesService.ReorderPolicies

rpc TogglePolicy(TogglePolicyRequest) returns (TogglePolicyResponse)

TogglePolicyRequest

message TogglePolicyRequest {
  google.protobuf.StringValue id = 1;
  google.protobuf.BoolValue enabled = 2;
}

TogglePolicyResponse

message TogglePolicyResponse {
  google.protobuf.StringValue id = 1;
  google.protobuf.BoolValue enabled = 2;
}

Example

grpcurl -H "Authorization: <cx_api_key>" -d '{
  "id": "abcd1",
  "enabled": true
}' ng-api-grpc.:443 com.coralogix.quota.v1.PoliciesService.TogglePolicy

Types

Policy

message Policy {
  google.protobuf.StringValue id = 1;
  google.protobuf.Int32Value company_id = 2;
  google.protobuf.StringValue name = 3;
  google.protobuf.StringValue description = 4;
  Priority priority = 5;
  google.protobuf.BoolValue deleted = 6;
  google.protobuf.BoolValue enabled = 7;
  google.protobuf.Int32Value order = 8;
  optional Rule application_rule = 9;
  optional Rule subsystem_rule = 10;
  oneof source_type_rules {
    LogRules log_rules = 11;
    SpanRules span_rules = 12;
  };
  optional google.protobuf.StringValue created_at = 13;
  optional google.protobuf.StringValue updated_at = 14;
  optional ArchiveRetention archive_retention = 15;
}

Rule

message Rule {
  RuleTypeId rule_type_id = 1;
  google.protobuf.StringValue name = 2;
}

Notes:

• For the values that need an exact match (e.g. RULE_TYPE_ID_IS, RULE_TYPE_ID_IS_NOT), the name property should be a list of values separated with a comma.

Examples

const rule1: Rule = {
  ruleTyleId: RuleTypeId.RULE_TYPE_ID_IS,
  name: 'service1,myService2,anotherService'
}

const rule2: Rule = {
  ruleTyleId: RuleTypeId.RULE_TYPE_ID_START_WITH,
  name: 'serv'
}

ArchiveRetention

message ArchiveRetention {
  google.protobuf.StringValue id = 1;
}

LogRules

message LogRules {
  repeated Severity severities = 1;
}

SpanRules

message SpanRules {
  optional Rule service_rule = 1;
  optional Rule action_rule = 2;
  repeated TagRule tag_rules = 3;
}

TagRule

message TagRule {
  RuleTypeId rule_type_id = 1;
  google.protobuf.StringValue tag_name = 2;
  google.protobuf.StringValue tag_value = 3;
}

Notes:

• Work the same way Rule works.

• tag_value is equivalent to name.

• Rule. tag_name refers to the name of the tag that the rule should impact.

PolicyOrder

message PolicyOrder {
  google.protobuf.Int32Value order = 1;
  google.protobuf.StringValue id = 2;
}

Enums

enum RuleTypeId {
  RULE_TYPE_ID_UNSPECIFIED = 0;
  reserved 1;
  RULE_TYPE_ID_IS = 2;
  RULE_TYPE_ID_IS_NOT = 3;
  RULE_TYPE_ID_START_WITH = 4;
  reserved 5;
  RULE_TYPE_ID_INCLUDES = 6;
  reserved 7;
}

enum Priority {
  PRIORITY_TYPE_UNSPECIFIED = 0;
  PRIORITY_TYPE_BLOCK = 1;
  PRIORITY_TYPE_LOW = 2;
  PRIORITY_TYPE_MEDIUM = 3;
  PRIORITY_TYPE_HIGH = 4;
}

enum Severity {
  SEVERITY_UNSPECIFIED = 0;
  SEVERITY_DEBUG = 1;
  SEVERITY_VERBOSE = 2;
  SEVERITY_INFO = 3;
  SEVERITY_WARNING = 4;
  SEVERITY_ERROR = 5;
  SEVERITY_CRITICAL = 6;
}

enum SourceType {
  SOURCE_TYPE_UNSPECIFIED = 0;
  SOURCE_TYPE_LOGS = 1;
  SOURCE_TYPE_SPANS = 2;
}

Additional Resources

Support

Need help?

Our world-class customer success team is available 24/7 to walk you through your setup and answer any questions that may come up.

Feel free to reach out to us via our in-app chat or by sending us an email at support@coralogix.com.