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.
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. 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 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 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 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 |
Notes:
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 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 HTTP 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].