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

View [this page](https://coralogix.com/docs/developer-portal/apis/tco-controls/tco-optimizer-http-api/index.md) to learn how to use our **TCO Optimizer HTTP API** to define, query, and manage your [TCO policy overrides](https://coralogix.com/docs/user-guides/account-management/tco-optimizer/#policies-and-filters), 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](https://coralogix.com/docs/developer-portal/apis/tco-controls/tco-tracing-policy-grpc-api/index.md) level defined in that policy.

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

[TagRule](https://coralogix.com/docs/developer-portal/apis/tco-controls/tco-tracing-policy-grpc-api/#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

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

**STEP 2**. To use this API you need to [create](https://coralogix.com/docs/user-guides/account-management/api-keys/api-keys/index.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` `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:

```bash
grpcurl -H "Authorization: <cx_api_key>" -d "<data_json_object>" <host_name> <grpc_method>
```

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

## 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

### rpc GetPolicy(GetPolicyRequest) returns (GetPolicyResponse)

**GetPolicyRequest**

```proto
message GetPolicyRequest {
  google.protobuf.StringValue id = 1;
}
```

| Field | Type                        | Description                 |
| ----- | --------------------------- | --------------------------- |
| id    | google.protobuf.StringValue | ID for the requested policy |

**GetPolicyResponse**

```proto
message GetPolicyResponse {
  Policy policy = 1;
}
```

| Field  | Type   | Description     |
| ------ | ------ | --------------- |
| policy | Policy | Policy returned |

**Example**

```bash
grpcurl -H "Authorization: <cx_api_key>" -d '{
  "id": "abcd"
}' api.[[DOMAIN_VALUE]]:443 com.coralogix.quota.v1.PoliciesService.GetPolicy
```

### rpc CreatePolicy(CreatePolicyRequest) returns (CreatePolicyResponse)

**CreatePolicyRequest**

```proto
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/user-guides/data-flow/s3-archive/archive-retention-policy/index.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**

```proto
message CreatePolicyResponse {
  Policy policy = 1;
}
```

| Field  | Type   | Description    |
| ------ | ------ | -------------- |
| policy | Policy | Policy created |

**Example**

```bash
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.[[DOMAIN_VALUE]]:443 com.coralogix.quota.v1.PoliciesService.CreatePolicy
```

### rpc UpdatePolicy(UpdatePolicyRequest) returns (UpdatePolicyResponse)

**UpdatePolicyRequest**

```proto
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/user-guides/data-flow/s3-archive/archive-retention-policy/index.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**

```proto
message UpdatePolicyResponse {
  Policy policy = 1;
}
```

| Field  | Type   | Description    |
| ------ | ------ | -------------- |
| policy | Policy | Policy updated |

**Example**

```bash
grpcurl -H "Authorization: <cx_api_key>" -d '{
  "id": "asdf",
  "name": "same name",
  "priority": "PRIORITY_TYPE_MEDIUM",
  "logRules": {
    "severities": [
      "SEVERITY_VERBOSE",
      "SEVERITY_WARNING"
    ]
  }
}' api.[[DOMAIN_VALUE]]:443 com.coralogix.quota.v1.PoliciesService.UpdatePolicy
```

### rpc GetCompanyPolicies(GetCompanyPoliciesRequest) returns (GetCompanyPoliciesResponse)

**GetCompanyPoliciesRequest**

```proto
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**

```proto
message GetCompanyPoliciesResponse {
  repeated Policy policies = 1;
}
```

| Field    | Type   | Description                  |
| -------- | ------ | ---------------------------- |
| policies | Policy | List of the company policies |

**Example**

```bash
grpcurl -H "Authorization: <cx_api_key>" -d '{
  "sourceType": "SOURCE_TYPE_SPANS",
  "enabledOnly": true
}' api.[[DOMAIN_VALUE]]:443 com.coralogix.quota.v1.PoliciesService.GetCompanyPolicies
```

### rpc DeletePolicy(DeletePolicyRequest) returns (DeletePolicyResponse)

**DeletePolicyRequest**

```proto
message DeletePolicyRequest {
  google.protobuf.StringValue id = 1;
}
```

| Field | Type                        | Description                |
| ----- | --------------------------- | -------------------------- |
| id    | google.protobuf.StringValue | ID of the policy to delete |

**DeletePolicyResponse**

```proto
message DeletePolicyResponse {
  google.protobuf.StringValue id = 1;
}
```

| Field | Type                        | Description                |
| ----- | --------------------------- | -------------------------- |
| id    | google.protobuf.StringValue | ID of the policy to delete |

**Example**

```bash
grpcurl -H "Authorization: <cx_api_key>" -d '{
  "id": "abcdid"
}' api.[[DOMAIN_VALUE]]:443 com.coralogix.quota.v1.PoliciesService.DeletePolicy
```

### rpc ReorderPolicies(ReorderPoliciesRequest) returns (ReorderPoliciesResponse)

**ReorderPoliciesRequest**

```proto
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**

```bash
message ReorderPoliciesResponse {
  repeated PolicyOrder orders = 1;
}
```

| Field  | Type        | Description                          |
| ------ | ----------- | ------------------------------------ |
| orders | PolicyOrder | [Repeated] New order of the policies |

**Example**

```bash
grpcurl -H "Authorization: <cx_api_key>" -d '{
  "orders": [
    {
      "order": 0,
      "id": "abcd1"
    },
    {
      "order": 1,
      "id": "abcd2"
    }
  ],
  "sourceType": "SOURCE_TYPE_LOGS"
}' api.[[DOMAIN_VALUE]]:443 com.coralogix.quota.v1.PoliciesService.ReorderPolicies
```

### rpc TogglePolicy(TogglePolicyRequest) returns (TogglePolicyResponse)

**TogglePolicyRequest**

```proto
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**

```proto
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**

```bash
grpcurl -H "Authorization: <cx_api_key>" -d '{
  "id": "abcd1",
  "enabled": true
}' api.[[DOMAIN_VALUE]]:443 com.coralogix.quota.v1.PoliciesService.TogglePolicy
```

## Types

### Policy

```proto
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/user-guides/data-flow/s3-archive/archive-retention-policy/index.md)** |

### Rule

```proto
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**

```ts
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

```proto
message ArchiveRetention {
  google.protobuf.StringValue id = 1;
}
```

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

### LogRules

```proto
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

```proto
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

```proto
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

```proto
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

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

```proto
enum Priority {
  PRIORITY_TYPE_UNSPECIFIED = 0;
  PRIORITY_TYPE_BLOCK = 1;
  PRIORITY_TYPE_LOW = 2;
  PRIORITY_TYPE_MEDIUM = 3;
  PRIORITY_TYPE_HIGH = 4;
}
```

```proto
enum Severity {
  SEVERITY_UNSPECIFIED = 0;
  SEVERITY_DEBUG = 1;
  SEVERITY_VERBOSE = 2;
  SEVERITY_INFO = 3;
  SEVERITY_WARNING = 4;
  SEVERITY_ERROR = 5;
  SEVERITY_CRITICAL = 6;
}
```

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

## Additional resources

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