This tutorial demonstrates how to use our TCO API to define, query, and manage your TCO’s tracing policy criteria.
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.
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:
Application
with the RuleTypeId RULE_TYPE_ID_IS
and the name default,app1
will match all spans with application name default
or app1
.Subsystem
with RuleTypeId RULE_TYPE_ID_START_WITH
and the name authSer
will match all spans with subsystem names that start with authSer
.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
.The API supports the following gRPCs:
Notes:
source_type_rules
appears, containing unique fields for each of them. 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:
rpc GetPolicy(GetPolicyRequest) returns (GetPolicyResponse)
GetPolicyRequest
message GetPolicyRequest { google.protobuf.StringValue id = 1; }
Field | Type | Description |
---|---|---|
id | google.protobuf.StringValue | ID for the requested policy |
GetPolicyResponse
message GetPolicyResponse { Policy policy = 1; }
Field | Type | Description |
---|---|---|
policy | Policy | Policy returned |
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; }; }
Field | Type | Description |
---|---|---|
name | google.protobuf.StringValue | Name for the new policy |
description | google.protobuf.StringValue | Description of the new policy. |
priority | Priority | TCO pipelines (HIGH, MEDIUM, LOW) |
application_rule | Rule | [Optional] Rule that targets specific application names |
subsystem_rule | Rule | [Optional] Rule that targets specific subsystem names |
archive_retention | ArchiveRetention | [Optional] See https://coralogix.com/docs/archive-retention-policy/ |
source_type_rules | oneof | Use only one of the following two fields |
log_rules | LogRules | Extra rules that can be defined for log policies |
span_rules | SpanRules | Extra rules that can be defined for span policies |
CreatePolicyResponse
message CreatePolicyResponse { Policy policy = 1; }
Field | Type | Description |
---|---|---|
policy | Policy | Policy created |
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; }; }
Field | Type | Description |
---|---|---|
id | google.protobuf.StringValue | ID of the policy to update |
name | google.protobuf.StringValue | Name of the updated policy |
description | google.protobuf.StringValue | Description of the updated policy |
priority | Priority | TCO pipelines (HIGH, MEDIUM, LOW) |
application_rule | Rule | [Optional] Rule that targets specific application names |
subsystem_rule | Rule | [Optional] Rule that targets specific subsystem names |
archive_retention | ArchiveRetention | [Optional] See https://coralogix.com/docs/archive-retention-policy/ |
source_type_rules | oneof | Use only one of the following two fields |
log_rules | LogRules | Extra rules that can be defined for log policies |
span_rules | SpanRules | Extra rules that can be defined for span policies |
UpdatePolicyResponse
message UpdatePolicyResponse { Policy policy = 1; }
Field | Type | Description |
---|---|---|
policy | Policy | Policy updated |
rpc GetCompanyPolicies(GetCompanyPoliciesRequest) returns (GetCompanyPoliciesResponse)
GetCompanyPoliciesRequest
message GetCompanyPoliciesRequest { google.protobuf.BoolValue enabled_only = 1; optional SourceType source_type = 2; }
Field | Type | Description |
---|---|---|
enabled_only | google.protobuf.BoolValue | Whether the policies returned should include only enabled policies or also disabled policies. True = only enabled policies |
source_type | SourceType | [Optional] Set the source type for policies to be returned. Possible values include SOURCE_TYPE_LOGS and SOURCE_TYPE_SPANS. If this field remains empty, you will receive all policies. |
GetCompanyPoliciesResponse
message GetCompanyPoliciesResponse { repeated Policy policies = 1; }
Field | Type | Description |
---|---|---|
policies | Policy | List of the company policies |
rpc DeletePolicy(DeletePolicyRequest) returns (DeletePolicyResponse)
DeletePolicyRequest
message DeletePolicyRequest { google.protobuf.StringValue id = 1; }
Field | Type | Description |
---|---|---|
id | google.protobuf.StringValue | ID of the policy to delete |
DeletePolicyResponse
message DeletePolicyResponse { google.protobuf.StringValue id = 1; }
Field | Type | Description |
---|---|---|
id | google.protobuf.StringValue | ID of the policy to delete |
rpc ReorderPolicies(ReorderPoliciesRequest) returns (ReorderPoliciesResponse)
ReorderPoliciesRequest
message ReorderPoliciesRequest { repeated PolicyOrder orders = 1; SourceType source_type = 2; }
Field | Type | Description |
---|---|---|
orders | PolicyOrder | [Repeated] New order in which to put the policies |
source_type | SourceType | Source type of the policies to reorder. See the SourceType enum below for possible values. |
ReorderPoliciesResponse
message ReorderPoliciesResponse { repeated PolicyOrder orders = 1; }
Field | Type | Description |
---|---|---|
orders | PolicyOrder | [Repeated] New order of the policies |
rpc TogglePolicy(TogglePolicyRequest) returns (TogglePolicyResponse)
TogglePolicyRequest
message TogglePolicyRequest { google.protobuf.StringValue id = 1; google.protobuf.BoolValue enabled = 2; }
Field | Type | Description |
---|---|---|
id | google.protobuf.StringValue | ID of the policy to enable or disable. |
enabled | google.protobuf.BoolValue | Whether the policy is enabled or disabled. True = policy is enabled |
TogglePolicyResponse
message TogglePolicyResponse { google.protobuf.StringValue id = 1; google.protobuf.BoolValue enabled = 2; }
Field | Type | Description |
---|---|---|
id | google.protobuf.StringValue | ID of the enabled or disabled policy. |
enabled | google.protobuf.BoolValue | Whether the policy is enabled or disabled. True = policy is enabled |
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; }
Field | Type | Description |
---|---|---|
id | google.protobuf.StringValue | ID of the policy |
company_id | google.protobuf.Int32Value | Company ID of the company that owns the policy |
name | google.protobuf.StringValue | Policy name |
description | google.protobuf.StringValue | Policy description |
priority | Priority | Policy priority |
deleted | google.protobuf.BoolValue | Whether or not the policy is deleted. True = deleted |
enabled | google.protobuf.BoolValue | Whether or not the policy is enabled. True = enabled |
order | google.protobuf.Int32Value | What number the policy comes in the order of policies |
application_rule | Rule | [Optional] Rule that targets specific application names |
subsystem_rule | Rule | [Optional] Rule that targets specific subsystem names. |
source_type_rules | oneof | Use one of the following two fields |
log_rules | LogRules | [Optional] Extra rules that can be defined for log policies |
span_rules | SpanRules | [Optional] Extra rules that can be defined for span policies |
created_at | google.protobuf.StringValue | [Optional] Time and date when a policy was created |
updated_at | google.protobuf.StringValue | [Optional] Time and date when a policy was updated. |
archive_retention | ArchiveRetention | [Optional] See https://coralogix.com/docs/archive-retention-policy/ |
message Rule { RuleTypeId rule_type_id = 1; google.protobuf.StringValue name = 2; }
Field | Type | Description |
---|---|---|
rule_type_id | RuleTypeID | Matching process is explained at the beginning of this page |
name | google.protobuf.StringValue | Rule name |
Note:
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' }
message ArchiveRetention { google.protobuf.StringValue id = 1; }
Field | Type | Description |
---|---|---|
id | google.protobuf.StringValue | See https://coralogix.com/docs/archive-retention-policy/ |
message LogRules { repeated Severity severities = 1; }
Field | Type | Description |
---|---|---|
severities | Severity | Every span is classified with a severity level. You can target spans with specific severity levels. |
message SpanRules { optional Rule service_rule = 1; optional Rule action_rule = 2; repeated TagRule tag_rules = 3; }
Field | Type | Description |
---|---|---|
service_rule | Rule | [Optional] Rule that targets specific service names |
action_rule | Rule | [Optional] Rule that targets specific action (operation) names |
tag_rules | TagRule | [Repeated] Rule that targets a specific tag name and value |
message TagRule { RuleTypeId rule_type_id = 1; google.protobuf.StringValue tag_name = 2; google.protobuf.StringValue tag_value = 3; }
Notes:
Rule
works. tag_value
is equivalent to name
.Rule
. tag_name
refers to the name of the tag that the rule should impact.message PolicyOrder { google.protobuf.Int32Value order = 1; google.protobuf.StringValue id = 2; }
Field | Type | Description |
---|---|---|
order | google.protobuf.Int32Value | Order for the policies to be in |
id | google.protobuf.StringValue | IDs of the different policies |
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; }
Documentation | TCO Optimizer TCO Optimizer API |
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 [email protected].