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 RuleTypeIdRULE_TYPE_ID_IS
and the namedefault,app1
will match all spans with application namedefault
orapp1
.A rule on
Subsystem
with RuleTypeIdRULE_TYPE_ID_START_WITH
and the nameauthSer
will match all spans with subsystem names that start withauthSer
.A TagRule with the name
tags.http.target
, RuleTypeIdRULE_TYPE_ID_INCLUDES
, and the value/api
will match all spans that have the tagtags.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:
You can find the 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 fieldsource_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
Field | Type | Description |
---|---|---|
id | google.protobuf.StringValue | ID for the requested policy |
GetPolicyResponse
Field | Type | Description |
---|---|---|
policy | Policy | Policy returned |
Example
grpcurl -H "Authorization: <cx_api_key>" -d '{
"id": "abcd"
}' https://ng-api-grpc.<span class="domain-value"></span>: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;
};
}
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 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
Field | Type | Description |
---|---|---|
policy | Policy | Policy created |
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"
}
}
}' https://ng-api-grpc.<span class="domain-value"></span>: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;
};
}
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 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
Field | Type | Description |
---|---|---|
policy | Policy | Policy updated |
Example
grpcurl -H "Authorization: <cx_api_key>" -d '{
"id": "asdf",
"name": "same name",
"priority": "PRIORITY_TYPE_MEDIUM",
"logRules": {
"severities": [
"SEVERITY_VERBOSE",
"SEVERITY_WARNING"
]
}
}' https://ng-api-grpc.<span class="domain-value"></span>: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;
}
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
Field | Type | Description |
---|---|---|
policies | Policy | List of the company policies |
Example
grpcurl -H "Authorization: <cx_api_key>" -d '{
"sourceType": "SOURCE_TYPE_SPANS",
"enabledOnly": true
}' https://ng-api-grpc.<span class="domain-value"></span>:443/ com.coralogix.quota.v1.PoliciesService.GetCompanyPolicies
rpc DeletePolicy(DeletePolicyRequest) returns (DeletePolicyResponse)
DeletePolicyRequest
Field | Type | Description |
---|---|---|
id | google.protobuf.StringValue | ID of the policy to delete |
DeletePolicyResponse
Field | Type | Description |
---|---|---|
id | google.protobuf.StringValue | ID of the policy to delete |
Example
grpcurl -H "Authorization: <cx_api_key>" -d '{
"id": "abcdid"
}' https://ng-api-grpc.<span class="domain-value"></span>:443/ com.coralogix.quota.v1.PoliciesService.DeletePolicy
rpc ReorderPolicies(ReorderPoliciesRequest) returns (ReorderPoliciesResponse)
ReorderPoliciesRequest
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
Field | Type | Description |
---|---|---|
orders | PolicyOrder | [Repeated] New order of the policies |
Example
grpcurl -H "Authorization: <cx_api_key>" -d '{
"orders": [
{
"order": 0,
"id": "abcd1"
},
{
"order": 1,
"id": "abcd2"
}
],
"sourceType": "SOURCE_TYPE_LOGS"
}' https://ng-api-grpc.<span class="domain-value"></span>: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;
}
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 |
Example
grpcurl -H "Authorization: <cx_api_key>" -d '{
"id": "abcd1",
"enabled": true
}' https://ng-api-grpc.<span class="domain-value"></span>: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;
}
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 Archive Retention Policy |
Rule
Field | Type | Description |
---|---|---|
rule_type_id | RuleTypeID | Matching process is explained at the beginning of this page |
name | google.protobuf.StringValue | Rule name |
Notes:
- For the values that need an exact match (e.g.
RULE_TYPE_ID_IS
,RULE_TYPE_ID_IS_NOT
), thename
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
Field | Type | Description |
---|---|---|
id | google.protobuf.StringValue | See Archive Retention Policy |
LogRules
Field | Type | Description |
---|---|---|
severities | Severity | Every span is classified with a severity level. You can target spans with specific severity levels. |
SpanRules
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 |
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 toname
.Rule
.tag_name
refers to the name of the tag that the rule should impact.
PolicyOrder
Field | Type | Description |
---|---|---|
order | google.protobuf.Int32Value | Order for the policies to be in |
id | google.protobuf.StringValue | IDs of the different policies |
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;
}
Additional Resources
Documentation | TCO Optimizer TCO Optimizer HTTP API |
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 [email protected].