Learn more about Streama© – the foundational technology behind our stateful streaming data platform. Learn More

TCO Optimizer API

This guide will help you use our TCO API to define, query, and manage your TCO’s Policy Criteria and Policy Overrides.

For more information about TCO capabilities, see TCO: Optimize your Total Logging Cost of Ownership

Usage

Please follow these steps to start using the Coralogix TCO API:

  • Make sure to select the correct API endpoint for your Account region
Cluster RegionBase API Endpoint
Europe (.com)https://api.coralogix.com/api/v1/external/tco/
US (.us)https://api.coralogix.us/api/v1/external/tco/
India (.in)https://api.app.coralogix.in/api/v1/external/tco/
  • Use the Alerts, Rules, and Tags API Key as the Bearer token.
    (Click your account’s icon on the top-right of the Coralogix UI, followed by “Settings”, and “API Access” on the left, [If you have not yet generated the key, please click “GENERATE NEW API KEY”]. Copy the key from here).

The following TCO API calls are supported:

  • Policy Criteria
    • Get all policies
      • URL – Base_API_Endpoint/policies
    • Get policy
      • URL – Base_API_Endpoint/policies/POLICYID
    • Create policy
      • URL – Base_API_Endpoint/policies
    • Update policy
      • URL – Base_API_Endpoint/policies/POLICYID
    • Reorder policies
      • URL – Base_API_Endpoint/policies/reorder
    • Delete policy
      • URL – Base_API_Endpoint/policies/POLICYID
  • Policy Overrides
    • Get override
      • URL – Base_API_Endpoin/overrides/OVERRIDEID
    • Get overrides
      • URL – Base_API_Endpoin/overrides
    • Get overrides with filter
      • URL – Base_API_Endpoint/overrides?subsystemName=subName&applicationName=appName
    • Create override
      • URL – Base_API_Endpoint/overrides
    • Create overrides bulk
      • URL – Base_API_Endpoint/overrides/bulk
    • Update override
      • URL – Base_API_Endpoin/overrides/OVERRIDEID
    • Update overrides bulk
      • URL – Base_API_Endpoint/overrides/bulk
    • Delete override
      • URL – Base_API_Endpoin/overrides/OVERRIDEID
    • Delete overrides bulk
      • URL – Base_API_Endpoint/overrides/bulk

Examples

Note: In the following examples, I am using Europe-based URLs for my requests since my account/team URL ends with .com. If your account/team URL ends with .us or .in you will need to modify the requests endpoints.

Note: The following set of requests contains severities (Policies), severity (Policy overrides) fields that contain numbers. Those numbers symbolize log severity: 1-debug, 2-verbose, 3-info, 4-warning, 5-error, 6-critical.

Policy Criteria

*** Create a new Policy Criterion ***

This example creates a Policy for application names that start with prod (e.g. prod, production, prod-eu) and subsystem names equal to web or mobile. The policy sets the priority for DEBUG, VERBOSE, INFO logs to medium.

Note: applicationName.type/subsystemName.type can be one of the following: “Starts With”, “Is”,  “Is Not”, “Includes”

Request:

curl --location --request POST 'https://api.coralogix.com/api/v1/external/tco/policies' \
--header 'Authorization: Bearer xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx' \
--header 'Content-Type: application/json' \
--data-raw ' {"name": "Policy Creation test","priority": "medium","severities": [1,2,3],"applicationName": {"type": "Starts With","rule": "prod"},"subsystemName": {"type": "Is","rule": ["web","mobile"]}}'

Response:

{
    "name": "Policy Creation test",
    "enabled": true,
    "priority": "medium",
    "order": 1,
    "applicationName": {
        "type": "Starts With",
        "rule": "prod"
    },
    "subsystemName": {
        "type": "Is",
        "rule": [
            "web",
            "mobile"
        ]
    },
    "severities": [
        1,
        2,
        3
    ]
}

Status Codes: 200.

*** Update a Policy Criterion ***

This example updates the name and severity selection for the Policy we created.

Note:

  • applicationName.type/subsystemName.type can be one of the following: “Starts With”, “Is”,  “Is Not”, “Includes”.
  • The body must include the policy name, priority, applicationName, subsystemName, and severities even when updating the name of the policy only.

Request:

curl --location --request PUT 'https://api.coralogix.com/api/v1/external/tco/policies/POLICYID' \
--header 'Authorization: Bearer xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx' \
--header 'Content-Type: application/json' \
--data-raw ' {"name": "Policy Creation test - updated","priority": "medium","severities": [1,2],"applicationName": {"type": "Starts With","rule": "prod"},"subsystemName": {"type": "Is","rule": ["web","mobile"]}}'

Response:

{
    "name": "Policy Creation test - updated",
    "enabled": true,
    "priority": "medium",
    "order": 1,
    "applicationName": {
        "type": "Starts With",
        "rule": "prod"
    },
    "subsystemName": {
        "type": "Is",
        "rule": [
            "web",
            "mobile"
        ]
    },
    "severities": [
        1,
        2
    ]
}

Status Codes: 200.

 

*** Reorder Policies ***

This example changes policies’ order.

Note:

  • The body only includes an array with the POLICYIDs. The first element in the array will be set as top policy and so on.

Request:

curl --location --request PUT 'https://api.coralogix.com/api/v1/external/tco/policies/reorder' \
--header 'Authorization: Bearer xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx' \
--header 'Content-Type: application/json' \
--data-raw '["0743219a-fe78-4401-9e1b-97be5cb2cfce","677f51f2-c4c7-4088-8ea7-abf3bbcc52a4"]'

Response:

[
    {
        "id": "0743219a-fe78-4401-9e1b-97be5cb2cfce",
        "order": 1
    },
    {
        "id": "677f51f2-c4c7-4088-8ea7-abf3bbcc52a4",
        "order": 2
    }
]

Status Codes: 200.

 

*** Get Policy ***

This example lists a specific policy.

Request:

curl --location --request GET 'https://api.coralogix.com/api/v1/external/tco/policies/POLICYID' \
--header 'Authorization: Bearer xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx' \
--header 'Content-Type: application/json' \
--data-raw ''

Response:

{
    "name": "Policy Creation test - updated",
    "enabled": true,
    "priority": "medium",
    "order": 1,
    "subsystemName": {
        "type": "Is",
        "rule": [
            "web",
            "mobile"
        ]
    },
    "severities": [
        1,
        2,
        3
    ],
    "applicationName": {
        "type": "Starts With",
        "rule": "prod"
    }
}

Status Codes: 200.

 

*** Get Policies ***

This example lists all existing policies.

Request:

curl --location --request GET 'https://api.coralogix.com/api/v1/external/tco/policies' \
--header 'Authorization: Bearer xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx' \
--header 'Content-Type: application/json' \
--data-raw ''

Response:

[
    {
        "name": "Policy Creation test",
        "priority": "medium",
        "order": 1,
        "subsystemName": {
            "type": "Is",
            "rule": [
                "web",
                "mobile"
            ]
        },
        "severities": [
            1,
            2,
            3
        ],
        "applicationName": {
            "type": "Starts With",
            "rule": "prod"
        }
    },
    {
        "name": "Policy Creation test - updated",
        "priority": "medium",
        "order": 2,
        "subsystemName": {
            "type": "Is",
            "rule": [
                "web",
                "mobile"
            ]
        },
        "severities": [
            1,
            2
        ],
        "applicationName": {
            "type": "Starts With",
            "rule": "prod"
        }
    }
]

Status Codes: 200.

 

*** Delete Policy ***

This example deletes an existing policy.

Request:

curl --location --request DELETE 'https://api.coralogix.com/api/v1/external/tco/policies/POLICYID' \
--header 'Authorization: Bearer xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx' \
--header 'Content-Type: application/json' \
--data-raw ''

Response:

{
    "message": "deleted policy with id POLICYID",
    "id": "POLICYID"
}

Status Codes: 200.

 

Policy Overrides

*** Create a new Policy Override ***

This example creates a Policy Override for application name dev and subsystem name metrics DEBUG logs and sets the priority to medium.

Request:

curl --location --request POST 'https://api.coralogix.com/api/v1/external/tco/overrides' \
--header 'Authorization: Bearer xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx' \
--header 'Content-Type: application/json' \
--data-raw '{"applicationName": "dev","subsystemName": "metrics","severity": 1,"priority": "medium"}'

Response:

{
    "applicationName": "dev",
    "subsystemName": "metrics",
    "severity": 1,
    "priority": "medium"
}

Status Codes: 200.

 

*** Create a Bulk Policy Override ***

This example creates a Policy Override for application name dev and subsystem name metrics logs and sets the priority for all severities classes to medium.

Request:

curl --location --request POST 'https://api.coralogix.com/api/v1/external/tco/overrides/bulk' \
--header 'Authorization: Bearer xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx' \
--header 'Content-Type: application/json' \
--data-raw '[{"applicationName": "dev","subsystemName": "metrics","severity": 1,"priority": "medium"},{"applicationName": "dev","subsystemName": "metrics","severity": 2,"priority": "medium"},{"applicationName": "dev","subsystemName": "metrics","severity": 3,"priority": "medium"},{"applicationName": "dev","subsystemName": "metrics","severity": 4,"priority": "medium"},{"applicationName": "dev","subsystemName": "metrics","severity": 5,"priority": "medium"},{"applicationName": "dev","subsystemName": "metrics","severity": 6,"priority": "medium"}]'

Response:

[
    {
        "status": 200,
        "override": {
            "applicationName": "dev",
            "subsystemName": "metrics",
            "severity": 1,
            "priority": "medium"
        }
    },
    {
        "status": 200,
        "override": {
            "applicationName": "dev",
            "subsystemName": "metrics",
            "severity": 2,
            "priority": "medium"
        }
    },
    {
        "status": 200,
        "override": {
            "applicationName": "dev",
            "subsystemName": "metrics",
            "severity": 3,
            "priority": "medium"
        }
    },
    {
        "status": 200,
        "override": {
            "applicationName": "dev",
            "subsystemName": "metrics",
            "severity": 4,
            "priority": "medium"
        }
    },
    {
        "status": 200,
        "override": {
            "applicationName": "dev",
            "subsystemName": "metrics",
            "severity": 5,
            "priority": "medium"
        }
    },
    {
        "status": 200,
        "override": {
            "applicationName": "dev",
            "subsystemName": "metrics",
            "severity": 6,
            "priority": "medium"
        }
    }
]

Status Codes: 200.

*** Update a Policy Override ***

This example updates a Policy Override for application name dev and subsystem name metrics DEBUG logs and updates the priority to low.

Request:

curl --location --request PUT 'https://api.coralogix.com/api/v1/external/tco/overrides/OVERRIDEID' \
--header 'Authorization: Bearer xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx' \
--header 'Content-Type: application/json' \
--data-raw '{"priority": "low","severity": 1,"applicationName": "dev","subsystemName": "metrics"}'

Response:

{
    "priority": "low",
    "severity": 1,
    "applicationName": "dev",
    "subsystemName": "metrics"
}

Status Codes: 200.

 

*** Update a Bulk Policy Override ***

This example updates a Policy Override for application name dev and subsystem name metrics logs and sets the priority for all severities classes to low.

Request:

curl --location --request PUT 'https://api.coralogix.com/api/v1/external/tco/overrides/bulk' \
--header 'Authorization: Bearer xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx' \
--header 'Content-Type: application/json' \
--data-raw '[{"id": "327f8448-05db-11ec-a5ad-0616c20b31c7","applicationName": "dev","subsystemName": "metrics","severity": 1,"priority": "low"},{"id": "3280e53b-05db-11ec-a5ad-0616c20b31c7","applicationName": "dev","subsystemName": "metrics","severity": 2,"priority": "low"},{"id": "3282542c-05db-11ec-a5ad-0616c20b31c7","applicationName": "dev","subsystemName": "metrics","severity": 3,"priority": "low"},{"id": "32864222-05db-11ec-a5ad-0616c20b31c7","applicationName": "dev","subsystemName": "metrics","severity": 4,"priority": "low"},{"id": "3287dab6-05db-11ec-a5ad-0616c20b31c7","applicationName": "dev","subsystemName": "metrics","severity": 5,"priority": "low"},{"id": "32892d2d-05db-11ec-a5ad-0616c20b31c7",applicationName": "dev","subsystemName": "metrics","severity": 6,"priority": "low"}]'

Response:

[
    {
        "status": 200,
        "override": {
            "applicationName": "dev",
            "subsystemName": "metrics",
            "severity": 1,
            "priority": "low"
        }
    },
    {
        "status": 200,
        "override": {
            "applicationName": "dev",
            "subsystemName": "metrics",
            "severity": 2,
            "priority": "low"
        }
    },
    {
        "status": 200,
        "override": {
            "applicationName": "dev",
            "subsystemName": "metrics",
            "severity": 3,
            "priority": "low"
        }
    },
    {
        "status": 200,
        "override": {
            "applicationName": "dev",
            "subsystemName": "metrics",
            "severity": 4,
            "priority": "low"
        }
    },
    {
        "status": 200,
        "override": {
            "applicationName": "dev",
            "subsystemName": "metrics",
            "severity": 5,
            "priority": "low"
        }
    },
    {
        "status": 200,
        "override": {
            "applicationName": "dev",
            "subsystemName": "metrics",
            "severity": 6,
            "priority": "low"
        }
    }
]

Status Codes: 200.

 

*** Get Policy Override ***

This example lists a specific policy override.

Request:

curl --location --request GET 'https://api.coralogix.com/api/v1/external/tco/overrides/OVERRIDEID' \
--header 'Authorization: Bearer xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'

Response:

{
    "id": "327f8448-05db-11ec-a5ad-0616c20b31c7",
    "name": "dev|metrics|DEBUG",
    "priority": "low",
    "severity": 1,
    "applicationName": "dev",
    "subsystemName": "metrics"
}

Status Codes: 200.

 

*** Get Policy Overrides ***

This example lists all existing policy overrides.

Request:

curl --location --request GET 'https://api.coralogix.com/api/v1/external/tco/overrides' \
--header 'Authorization: Bearer xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'

 

*** Get Policy Overrides with Filter ***

This example lists all existing policy overrides for application name dev and subsystem name metrics.

Request:

curl --location --request GET 'https://api.coralogix.com/api/v1/external/tco/overrides?subsystemName=metrics&applicationName=dev' \
--header 'Authorization: Bearer xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'

Response:

[
    {
        "status": 200,
        "override": {
            "applicationName": "dev",
            "subsystemName": "metrics",
            "severity": 1,
            "priority": "low"
        }
    },
    {
        "status": 200,
        "override": {
            "applicationName": "dev",
            "subsystemName": "metrics",
            "severity": 2,
            "priority": "low"
        }
    },
    {
        "status": 200,
        "override": {
            "applicationName": "dev",
            "subsystemName": "metrics",
            "severity": 3,
            "priority": "low"
        }
    },
    {
        "status": 200,
        "override": {
            "applicationName": "dev",
            "subsystemName": "metrics",
            "severity": 4,
            "priority": "low"
        }
    },
    {
        "status": 200,
        "override": {
            "applicationName": "dev",
            "subsystemName": "metrics",
            "severity": 5,
            "priority": "low"
        }
    },
    {
        "status": 200,
        "override": {
            "applicationName": "dev",
            "subsystemName": "metrics",
            "severity": 6,
            "priority": "low"
        }
    }
]

Status Codes: 200.

 

*** Delete Policy Override ***

This example deletes an existing policy override.

Request:

curl --location --request DELETE 'https://api.coralogix.com/api/v1/external/tco/overrides/OVERRIDEID' \
--header 'Authorization: Bearer xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx' \
--data-raw ''

 

*** Delete Bulk Policy Override ***

This example deletes an existing bulk policy override.

Request:

curl --location --request DELETE 'https://api.coralogix.com/api/v1/external/tco/overrides/bulk' \
--header 'Authorization: Bearer xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx' \
--header 'Content-Type: application/json' \
--data-raw '[{"id": "327f8448-05db-11ec-a5ad-0616c20b31c7","priority": "low","severity": 1,"applicationName": "dev","subsystemName": "metrics"},{"id": "3280e53b-05db-11ec-a5ad-0616c20b31c7","priority": "low","severity": 2,"applicationName": "dev","subsystemName": "metrics"},{"id": "3282542c-05db-11ec-a5ad-0616c20b31c7","priority": "low","severity": 3,"applicationName": "dev","subsystemName": "metrics"},{"id": "32864222-05db-11ec-a5ad-0616c20b31c7","priority": "low","severity": 4,"applicationName": "dev","subsystemName": "metrics"},{"id": "32892d2d-05db-11ec-a5ad-0616c20b31c7","priority": "low","severity": 6,"applicationName": "dev","subsystemName": "metrics"}]'

 

That’s it, you are good to go!

For any assistance, or if you would like to receive a ready-to-go postman library containing all these requests, please reach out to Coralogix support (support@coralogix.com) or via Intercom.