cURL Version Tags

Open in ChatGPTOpen in Claude

Set up cURL Version Tags with Coralogix.

Setup

You can add version tags per application and subsystem using cURL:

URL: Choose the https://api./api/v1/external/tags endpoint that corresponds to your Coralogix domain using the domain selector at the top of the page.

API Key: To use this API you need to create 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
CICDIntegration	VERSION-BENCHMARK-TAGS:READ VERSION-BENCHMARKS-REPORTS:READ VERSION-BENCHMARK-TAGS:UPDATE	View Version Benchmark Tags View Version Benchmark Reports Modify Version Benchmark Tags

Method: POST

Body Schema:

{"iconUrl": string,"name": string,"timestamp": date type (JavaScript date string or epoch milliseconds)"application": string[]"subsystem": string[]}

Application: Your Application name.

Subsystem: Your Subsystem(s) name(s). You can input more than one subsystem name, use comma delimiter ‘,’ between Subsystem names.

Name: Your Version Tag name.

Timestamp: Tag Timestamp. (This is OPTIONAL: If a timestamp is not supplied, the current timestamp will be applied).

IconUrl: Tag's Picture. (This is OPTIONAL: Use an URL (URL encoded) to a valid image file uploaded to a public repository)

Supported Image Formats: png, jpeg, SVG.

Maximum File Size: 50 Kilobytes.

Note: If the URL to the image contains spaces, please use %20.

For example:

https://www.myimagesite.com/Path%20To%20The%20Image.png.

Example (GET):

curl --location --request GET 'https://api.eu2.coralogix.com/api/v1/external/tags/add?key=&application=Application_Name,Application_Name2&subsystem=Subsystem1,Subsystem2,Subsystem3&name=MyFirstTag&timestamp=2020-06-23:09:00:00&iconUrl=your_icon_url'

Example (POST):

curl --location --request POST 'https://api.eu2.coralogix.com/api/v1/external/tags' \
--header 'Authorization: Bearer <cx_api_key>' \
--header 'Content-Type: application/json' \
--data-raw '{
"timestamp": 1617793927675,
"name": "test tag",
"application": ["prd", "dev"],
"subsystem": ["app", "mobile"],
"iconUrl": "my-avatar.png"
}'

Note: application and subsystem should always be contained between square brackets, even if it is an array of one element, for example:

"application": ["prd"],
"subsystem": ["app"]

Send deployment events

Send a deployment to the Coralogix ops events API as well, and it appears as an event marker on your APM charts, so you can line a latency or error-rate change up with the deployment that caused it. Use this from any pipeline that can run curl.

What you need

• A Send Your Data API key with the OpsEvents role preset. The ops events API rejects any other key type or preset, including the CICDIntegration key used for version tags, with 403 Forbidden.
• The ops events endpoint for your Coralogix domain. Use the domain selector at the top of this page to resolve it: https://api./v1/ops-events
• The service name and environment exactly as they appear in APM. They must equal the service.name and deployment.environment.name resource attributes your service reports. An event that matches no service is still stored, but appears only under All events.

Send the event

For a deployment, send a cdEvent with system set to the matching CD_SYSTEM_* value: CD_SYSTEM_GITHUB, CD_SYSTEM_ARGOCD, CD_SYSTEM_JENKINS, CD_SYSTEM_GITLAB, CD_SYSTEM_BITBUCKET, CD_SYSTEM_AZURE_DEVOPS, or CD_SYSTEM_SPINNAKER. cdEvent.system and cdEvent.pipeline.name are required.

curl -sS --fail-with-body -X POST 'https://api.eu2.coralogix.com/v1/ops-events' \
  -H "Authorization: Bearer $CX_API_KEY" \
  -H 'Content-Type: application/json' \
  --data-binary @- <<EOF
{
  "opsEvent": {
    "timestamp": "$(date -u +%Y-%m-%dT%H:%M:%SZ)",
    "description": "payments-api v2.14.0 deployed to production",
    "attributes": {
      "service": { "name": "payments-api" },
      "environment": "production"
    },
    "cdEvent": {
      "system": "CD_SYSTEM_JENKINS",
      "pipeline": {
        "name": "deploy-production",
        "run": { "id": "1287", "url": "https://jenkins.example.com/job/deploy-production/1287/" },
        "result": { "status": "PIPELINE_RESULT_STATUS_SUCCESS" }
      },
      "vcs": {
        "system": "VCS_SYSTEM_GITHUB",
        "type": "VCS_REF_TYPE_BRANCH",
        "repository": { "name": "org/payments-api", "url": "https://github.com/org/payments-api" },
        "ref": { "head": { "name": "main", "revision": "abc123def456789abcdef0123456789abcdef01" } }
      }
    }
  }
}
EOF

Send a customEvent for a deployment from a CI/CD system that has no CD_SYSTEM_* value, or for an event that isn't a deployment, such as an incident, feature-flag change, or campaign. Carry any details in attributes.additional. The marker appears in the Custom events group on your charts.

curl -sS --fail-with-body -X POST 'https://api.eu2.coralogix.com/v1/ops-events' \
  -H "Authorization: Bearer $CX_API_KEY" \
  -H 'Content-Type: application/json' \
  --data-binary @- <<EOF
{
  "opsEvent": {
    "timestamp": "$(date -u +%Y-%m-%dT%H:%M:%SZ)",
    "description": "payments-api v2.14.0 deployed to production",
    "attributes": {
      "service": { "name": "payments-api" },
      "environment": "production",
      "additional": {
        "cdSystem": "my-ci",
        "pipeline": { "name": "deploy-production", "run": { "id": "1287" } }
      }
    },
    "customEvent": {}
  }
}
EOF

A successful request returns the server-generated event id. The marker then appears on the service's APM charts; see Event markers for how to show it and for the full field reference. The API rejects a timestamp more than 24 hours from the time the request is received, so send the event from the pipeline as it runs rather than backfilling.

Additional resources

Coralogix Endpoints	Coralogix Endpoints