# TCO tracing policy gRPC API

Copy as Markdown[Open in ChatGPT](https://chatgpt.com/?q=Read%20https%3A%2F%2Fcoralogix.com%2Fdocs%2Fdeveloper-portal%2Fapis%2Ftco-controls%2Ftco-tracing-policy-grpc-api.md%20and%20help%20me%20with%20my%20question%20about%20this%20Coralogix%20documentation%20page.)[Open in Claude](https://claude.ai/new?q=Read%20https%3A%2F%2Fcoralogix.com%2Fdocs%2Fdeveloper-portal%2Fapis%2Ftco-controls%2Ftco-tracing-policy-grpc-api.md%20and%20help%20me%20with%20my%20question%20about%20this%20Coralogix%20documentation%20page.)[API reference](https://coralogix.com/docs/docs/api-reference/v5/policies-service)

This tutorial demonstrates how to use our **TCO Tracing gPRC API** to define, query, and manage your [TCO policy criteria](https://coralogix.com/docs/docs/user-guides/account-management/tco-optimizer/.md#policies-and-filters), used both for spans and logs.

View [this page](https://coralogix.com/docs/docs/developer-portal/apis/tco-controls/tco-optimizer-http-api/.md) to learn how to use our **TCO Optimizer HTTP API** to define, query, and manage your [TCO policy overrides](https://coralogix.com/docs/docs/user-guides/account-management/tco-optimizer/.md#policies-and-filters), used exclusively for logs.

## Overview[​](#overview "Direct link to 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[​](#matching-process "Direct link to Matching process")

Spans that match all rules in a policy will be assigned the [priority](https://coralogix.com/docs/docs/developer-portal/apis/tco-controls/tco-tracing-policy-grpc-api/.md) level defined in that policy.

Every [rule](https://coralogix.com/docs/docs/developer-portal/apis/tco-controls/tco-tracing-policy-grpc-api/.md#rule) targets a property (e.g. `Application`) by `RuleTypeId`.

[TagRule](https://coralogix.com/docs/docs/developer-portal/apis/tco-controls/tco-tracing-policy-grpc-api/.md#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[​](#how-to-send-grpc-requests "Direct link to How to Send gRPC requests")

**STEP 1**. Install [grpcurl](https://github.com/fullstorydev/grpcurl).

**STEP 2**. To use this API you need to [create](https://coralogix.com/docs/docs/user-guides/account-management/api-keys/api-keys/.md) 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`<br />`LOGS.TCO:UPDATEPOLICIES`<br />`SPANS.TCO:READPOLICIES`<br />`SPANS.TCO:UPDATEPOLICIES`<br />`METRICS.TCO:READPOLICIES`<br />`METRICS.TCO:UPDATEPOLICIES` | View Logs TCO Policies<br />Manage Logs TCO Policies<br />View Tracing TCO Policies<br />Manage Tracing TCO Policies<br />View Metrics TCO Policies<br />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>
```

Choose the <!-- -->api.:443<!-- --> endpoint that corresponds to your Coralogix [domain](https://coralogix.com/docs/docs/user-guides/account-management/account-settings/coralogix-domain/.md) using the domain selector at the top of the page.

## Supported API calls[​](#supported-api-calls "Direct link to 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[​](#api-calls "Direct link to API calls")

### rpc GetPolicy(GetPolicyRequest) returns (GetPolicyResponse)[​](#rpc-getpolicygetpolicyrequest-returns-getpolicyresponse "Direct link to 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 |

**Example**

```
grpcurl -H "Authorization: <cx_api_key>" -d '{

  "id": "abcd"

}' api.eu2.coralogix.com:443 com.coralogix.quota.v1.PoliciesService.GetPolicy
```

### rpc CreatePolicy(CreatePolicyRequest) returns (CreatePolicyResponse)[​](#rpc-createpolicycreatepolicyrequest-returns-createpolicyresponse "Direct link to 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**](https://coralogix.com/docs/docs/user-guides/data-flow/s3-archive/archive-retention-policy/.md) |
| 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 |

**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"

    }

  }

}' api.eu2.coralogix.com:443 com.coralogix.quota.v1.PoliciesService.CreatePolicy
```

### rpc UpdatePolicy(UpdatePolicyRequest) returns (UpdatePolicyResponse)[​](#rpc-updatepolicyupdatepolicyrequest-returns-updatepolicyresponse "Direct link to 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](https://coralogix.com/docs/docs/user-guides/data-flow/s3-archive/archive-retention-policy/.md)** |
| 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 |

**Example**

```
grpcurl -H "Authorization: <cx_api_key>" -d '{

  "id": "asdf",

  "name": "same name",

  "priority": "PRIORITY_TYPE_MEDIUM",

  "logRules": {

    "severities": [

      "SEVERITY_VERBOSE",

      "SEVERITY_WARNING"

    ]

  }

}' api.eu2.coralogix.com:443 com.coralogix.quota.v1.PoliciesService.UpdatePolicy
```

### rpc GetCompanyPolicies(GetCompanyPoliciesRequest) returns (GetCompanyPoliciesResponse)[​](#rpc-getcompanypoliciesgetcompanypoliciesrequest-returns-getcompanypoliciesresponse "Direct link to 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 |

**Example**

```
grpcurl -H "Authorization: <cx_api_key>" -d '{

  "sourceType": "SOURCE_TYPE_SPANS",

  "enabledOnly": true

}' api.eu2.coralogix.com:443 com.coralogix.quota.v1.PoliciesService.GetCompanyPolicies
```

### rpc DeletePolicy(DeletePolicyRequest) returns (DeletePolicyResponse)[​](#rpc-deletepolicydeletepolicyrequest-returns-deletepolicyresponse "Direct link to 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 |

**Example**

```
grpcurl -H "Authorization: <cx_api_key>" -d '{

  "id": "abcdid"

}' api.eu2.coralogix.com:443 com.coralogix.quota.v1.PoliciesService.DeletePolicy
```

### rpc ReorderPolicies(ReorderPoliciesRequest) returns (ReorderPoliciesResponse)[​](#rpc-reorderpoliciesreorderpoliciesrequest-returns-reorderpoliciesresponse "Direct link to 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 |

**Example**

```
grpcurl -H "Authorization: <cx_api_key>" -d '{

  "orders": [

    {

      "order": 0,

      "id": "abcd1"

    },

    {

      "order": 1,

      "id": "abcd2"

    }

  ],

  "sourceType": "SOURCE_TYPE_LOGS"

}' api.eu2.coralogix.com:443 com.coralogix.quota.v1.PoliciesService.ReorderPolicies
```

### rpc TogglePolicy(TogglePolicyRequest) returns (TogglePolicyResponse)[​](#rpc-togglepolicytogglepolicyrequest-returns-togglepolicyresponse "Direct link to 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

}' api.eu2.coralogix.com:443 com.coralogix.quota.v1.PoliciesService.TogglePolicy
```

## Types[​](#types "Direct link to Types")

### Policy[​](#policy "Direct link to 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](https://coralogix.com/docs/docs/user-guides/data-flow/s3-archive/archive-retention-policy/.md)** |

### Rule[​](#rule "Direct link to 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                                                   |

**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[​](#archiveretention "Direct link to ArchiveRetention")

```
message ArchiveRetention {

  google.protobuf.StringValue id = 1;

}
```

| Field | Type                        | Description                                                                                                                       |
| ----- | --------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| id    | google.protobuf.StringValue | See [**Archive Retention Policy**](https://coralogix.com/docs/docs/user-guides/data-flow/s3-archive/archive-retention-policy/.md) |

### LogRules[​](#logrules "Direct link to 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[​](#spanrules "Direct link to 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[​](#tagrule "Direct link to 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[​](#policyorder "Direct link to 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[​](#enums "Direct link to 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[​](#additional-resources "Direct link to Additional resources")

|                     |                                                                                                                                                                                                                                |
| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Documentation       | [TCO Optimizer](https://coralogix.com/docs/docs/user-guides/account-management/tco-optimizer/.md)<br />[TCO Optimizer HTTP API](https://coralogix.com/docs/docs/developer-portal/apis/tco-controls/tco-optimizer-http-api/.md) |
| Coralogix Endpoints | [Coralogix Endpoints](https://coralogix.com/docs/docs/integrations/coralogix-endpoints/.md)                                                                                                                                    |