TCO Tracing Policy gRPC API

This tutorial demonstrates how to use our TCO API to define, query, and manage your TCO’s tracing policy criteria.

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.

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. Therefore, in some requests, the field 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:

API calls

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

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 https://coralogix.com/docs/archive-retention-policy/

Rule

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:

• 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;
}

Field	Type	Description
id	google.protobuf.StringValue	See https://coralogix.com/docs/archive-retention-policy/

LogRules

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.

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 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;
}

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;
}

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

Additional Resources

Documentation

TCO Optimizer TCO Optimizer 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].