Copy as Markdown[Open in ChatGPT](https://chatgpt.com/?q=Read%20https%3A%2F%2Fcoralogix.com%2Fdocs%2Fuser-guides%2Fmonitoring-and-insights%2Fannotations.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%2Fuser-guides%2Fmonitoring-and-insights%2Fannotations.md%20and%20help%20me%20with%20my%20question%20about%20this%20Coralogix%20documentation%20page.)

# Annotations

Annotations mark deployments, alerts, feature-flag changes, campaigns, and configuration changes on your charts, so you can line a latency spike, error surge, or throughput drop up with the change that caused it. Every dated event sits on the same time axis as your data, so you can answer "what changed?" on the chart itself, without switching tools.

[![An annotation on the Explore logs chart: a deployment marker with a hover tooltip showing the count by severity at that time and the deployment event, its service, and environment.](/docs/assets/images/explore-annotations-8f1644195a0ac21a49b28e463819e820.webp)](https://coralogix.com/docs/assets/images/explore-annotations-8f1644195a0ac21a49b28e463819e820.webp)

The same events show up wherever you analyze your data:

* **APM**: deployment and custom-event annotations overlay on the catalog charts and on the charts in a service or database drilldown. See [Annotations in APM](#annotations-in-apm).
* **Explore**: the same annotations overlay on the time-series chart above your logs and spans results, alongside version benchmark markers. See [Annotations in Explore](#annotations-in-explore).

## What you need[​](#what-you-need "Direct link to What you need")

* Access to the surface you want to analyze: APM or Explore.
* Events sent to Coralogix. Deployment and custom annotations come from the ops-events ingest API (see [Send events to Coralogix](#send-events-to-coralogix)); version benchmark markers come from the version-tags API (see [Version benchmark annotations](#version-benchmark-annotations-legacy)).

## Annotation types[​](#annotation-types "Direct link to Annotation types")

Coralogix draws each type in its own color, with a matching entry in the chart legend. Only types that have events in the current time range appear.

* **Deployments**: deployments and releases from your CD pipeline, sent as a `cdEvent` through the ops-events ingest API. These annotations carry pipeline and version-control metadata: the pipeline run, repository, branch or tag, and commit.
* **Custom events**: alerts, feature flags, campaigns, and configuration changes, sent as a `customEvent` through the ops-events ingest API.
* **Version benchmark**: in Explore, each released version measured against the one before it, sourced from the version-tags API. This is a legacy type that Coralogix is phasing out in favor of deployment annotations. See [Version benchmark annotations](#version-benchmark-annotations-legacy).

## Turn on annotations[​](#turn-on-annotations "Direct link to Turn on annotations")

Open the **Annotations** control, turn annotations on, and select which event types to show. Select at least one type, or no annotations draw. Your selections persist across sessions. One control covers every chart on the screen.

[![The open Annotations control in Explore: a toggle, a description with a Learn more link, the annotation-type picker (Deployments, Custom events, and more), and vertical annotation markers down the results chart.](/docs/assets/images/annotations-control-b1c0c2d5ec05c9cc03c624190bd6f940.webp)](https://coralogix.com/docs/assets/images/annotations-control-b1c0c2d5ec05c9cc03c624190bd6f940.webp)

Annotations draw as vertical markers across the chart, aligned to event timestamps, and follow the current time range. Hover a marker to read the event's description, service, and environment. When several events share a time bucket, the tooltip shows the first with a count of how many landed there; Cmd or Ctrl-click to pin it and read the full list. Select an event for its actions: view the event's details, copy its description, service, or environment, open it in its CD system, and, when the event carries them, open the pipeline run or repository.

[![An annotation tooltip reading 4 events at this time, with a deployment event and its environment, a +3 more line, and the hint to select for actions or Cmd-click to pin.](/docs/assets/images/annotations-tooltip-d3af064dc8a1db41e38642cc2ea8e18e.webp)](https://coralogix.com/docs/assets/images/annotations-tooltip-d3af064dc8a1db41e38642cc2ea8e18e.webp)

## Event details[​](#event-details "Direct link to Event details")

Select **Open event info** on an event, from the chart tooltip or its actions menu, to open its details drawer. The drawer shows the event's attributes in **Table**, **JSON**, and **Raw** views, each with search and copy, and a link you can copy to share the event. Step through the events in the current range with the next and previous controls.

For an event tied to a service, the drawer also charts the event's impact: the service's **requests**, **errors**, and **latency** for an equal span before and after the event. Choose the **impact window** (1, 3, 6, or 12 hours, centered on the event) and switch the chart scale between linear and logarithmic.

## Annotations in Explore[​](#annotations-in-explore "Direct link to Annotations in Explore")

In [Explore](https://coralogix.com/docs/user-guides/data_exploration.md), annotations overlay on the [time-series chart](https://coralogix.com/docs/user-guides/data_exploration/timeseries-chart.md) above your results, on both the logs and spans datasets. Open the **Annotations** control in the Explore header to turn them on and select which types to show; the setting is shared across every query tab on the page.

What annotations match depends on the dataset:

* **Logs**: annotations follow the current time range. Logs carry no service for an event to match, so every event in the range appears.
* **Spans**: annotations follow the current time range and the service and environment your query filters to.

## Annotations in APM[​](#annotations-in-apm "Direct link to Annotations in APM")

In APM, annotations overlay on the catalog overview charts and on the charts in a service or database drilldown. There you can scope them to the service you're analyzing, to that service and its related services, or to every event in your account. For the full APM workflow, see [Annotations](https://coralogix.com/docs/user-guides/apm-v2/features/annotations.md).

[![The Annotations control in APM, with the annotation-type picker and the event-scope options: Service events, Service and related events, and All events.](/docs/assets/images/apm-annotations-2722a83be5302840cae2cff74f756a8b.webp)](https://coralogix.com/docs/assets/images/apm-annotations-2722a83be5302840cae2cff74f756a8b.webp)

## Send events to Coralogix[​](#send-events-to-coralogix "Direct link to Send events to Coralogix")

Deployment and custom annotations come from the Coralogix ops-events ingest API. Send an event once and it appears as an annotation in APM and Explore, scoped by the attributes you include. Coralogix also stores each event in the `default/ops.events` dataset, so you can query your events in Explore with DataPrime.

The API is available as REST and gRPC:

* **REST**: send a `POST` request to
  <!-- -->
  https\://api./v1/ops-events
  <!-- -->
  .
* **gRPC**: call `com.coralogixapis.opsevents.v1.OpsEventsIngestService/CreateOpsEvent`.

Authenticate with a **Send Your Data Key** in the `Authorization` header: `Authorization: Bearer <api-key>`. The key must be allowed to send ops events: when you [create the key](https://coralogix.com/docs/user-guides/account-management/api-keys/api-keys.md#create-an-api-key), select the **OpsEvents** role preset. A key created with a different preset (for example, **SendData**) is rejected with `403 Forbidden`.

Each event is one of two kinds:

* `cdEvent`: a CI/CD deploy, with pipeline and version-control metadata. Draws as a **Deployments** annotation.
* `customEvent`: a generic event such as an alert, feature flag, campaign, or configuration change. Draws as a **Custom events** annotation.

### Minimum required fields[​](#minimum-required-fields "Direct link to Minimum required fields")

* `timestamp`: an RFC 3339 timestamp for when the event happened. It must be within 24 hours of the current server time.
* `description`: a short, human-readable summary, shown on hover. Must not be empty.
* One event object: either `cdEvent` or `customEvent`.

### Fields that unlock filtering and correlation[​](#fields-that-unlock-filtering-and-correlation "Direct link to Fields that unlock filtering and correlation")

* `attributes.service.name`: links the event to a service. An event without it appears only in the account-wide scope.
* `attributes.environment`: scopes the event to an environment (for example, `production`, `staging`).
* `cdEvent.system`: the CI/CD system. One of `CD_SYSTEM_GITHUB`, `CD_SYSTEM_ARGOCD`, `CD_SYSTEM_JENKINS`, `CD_SYSTEM_GITLAB`, `CD_SYSTEM_BITBUCKET`, `CD_SYSTEM_AZURE_DEVOPS`, `CD_SYSTEM_SPINNAKER`.
* `cdEvent.pipeline.name`, `cdEvent.pipeline.run.id`, `cdEvent.pipeline.run.url`, `cdEvent.pipeline.run.durationSeconds`: pipeline run details and a deep link.
* `cdEvent.pipeline.result.status`: one of `PIPELINE_RESULT_STATUS_SUCCESS`, `_FAILURE`, `_TIMEOUT`, `_CANCELLATION`, `_ERROR`, `_SKIP`.
* `cdEvent.pipeline.task.name`, `cdEvent.pipeline.task.type`: task identifier and kind (`PIPELINE_TASK_TYPE_BUILD`, `_TEST`, `_DEPLOY`).
* `cdEvent.vcs.system`, `cdEvent.vcs.type`: version-control provider (`VCS_SYSTEM_GITHUB`, `_GITLAB`, `_BITBUCKET`) and reference kind (`VCS_REF_TYPE_BRANCH`, `_TAG`).
* `cdEvent.vcs.repository.name`, `cdEvent.vcs.repository.url`, `cdEvent.vcs.ref.head.name`, `cdEvent.vcs.ref.head.revision`: repository and branch, tag, or commit.

Stored events strip the enum prefix (`CD_SYSTEM_ARGOCD` becomes `argocd`, and so on), so DataPrime queries against `default/ops.events` filter on the lowercase form.

### Example: send a deployment event[​](#example-send-a-deployment-event "Direct link to Example: send a deployment event")

Set `$CX_API_KEY` to a **Send Your Data Key** that has the **OpsEvents** role preset, and send with a current `timestamp`:

```
curl -X POST https://api.eu2.coralogix.com/v1/ops-events \

  -H "Authorization: Bearer $CX_API_KEY" \

  -H "Content-Type: application/json" \

  -d '{

    "opsEvent": {

      "timestamp": "2026-07-13T10:15:00Z",

      "description": "payments-api v2.14.0 deployed to production",

      "attributes": {

        "service": { "name": "payments-api" },

        "environment": "production"

      },

      "cdEvent": {

        "system": "CD_SYSTEM_GITHUB",

        "pipeline": {

          "name": "deploy-production",

          "run": { "id": "9753949763", "url": "https://github.com/org/payments/actions/runs/9753949763" },

          "result": { "status": "PIPELINE_RESULT_STATUS_SUCCESS" }

        }

      }

    }

  }'
```

### Example: send a custom event[​](#example-send-a-custom-event "Direct link to Example: send a custom event")

A custom event needs only a current `timestamp`, a `description`, and an empty `customEvent` object. Attach any structured data under `attributes.additional`:

```
curl -X POST https://api.eu2.coralogix.com/v1/ops-events \

  -H "Authorization: Bearer $CX_API_KEY" \

  -H "Content-Type: application/json" \

  -d '{

    "opsEvent": {

      "timestamp": "2026-07-13T13:45:00Z",

      "description": "quarterly feature flag rollout started",

      "attributes": {

        "environment": "production",

        "additional": { "flag": "new-billing-ui", "rolloutPercent": 25 }

      },

      "customEvent": {}

    }

  }'
```

### Send events from your CI/CD pipeline[​](#send-events-from-your-cicd-pipeline "Direct link to Send events from your CI/CD pipeline")

Each of these guides has a ready-to-use step or configuration that sends a deployment event on every run:

* [GitHub Actions](https://coralogix.com/docs/developer-portal/apis/version-tags/github-version-tags.md#send-deployment-events)
* [Argo CD](https://coralogix.com/docs/developer-portal/apis/version-tags/argo-cd-version-tags.md#send-deployment-events)
* [GitLab](https://coralogix.com/docs/developer-portal/apis/version-tags/gitlab-version-tags.md#send-deployment-events)
* [Bitbucket](https://coralogix.com/docs/developer-portal/apis/version-tags/bitbucket-version-tags.md#send-deployment-events)
* [Azure DevOps](https://coralogix.com/docs/developer-portal/apis/version-tags/microsoft-azure-devops-server-version-tags.md#send-deployment-events)
* [Spinnaker](https://coralogix.com/docs/developer-portal/apis/version-tags/spinnaker-version-tags.md#send-deployment-events)
* [Any other pipeline, with cURL](https://coralogix.com/docs/developer-portal/apis/version-tags/curl-version-tags.md#send-deployment-events)

## Version benchmark annotations (legacy)[​](#version-benchmark-annotations-legacy "Direct link to Version benchmark annotations (legacy)")

Version benchmark markers come from the [Version Benchmarks](https://coralogix.com/docs/user-guides/monitoring-and-insights/version-benchmarks.md) version-tags API rather than the ops-events API. In Explore, they mark each released version so you can line a shift in your data up with the version that preceded it.

Legacy feature

Version Benchmarks is a legacy capability. Annotations are replacing it as the way to mark deployments and events on your charts, and Version Benchmarks will be deprecated in a future release.

Version Benchmarks stays available in the meantime. Annotations don't yet cover every Version Benchmarks capability, so you can keep using it where you rely on those. For deployments, send events through the [ops-events ingest API](#send-events-to-coralogix) so they appear as **Deployments** annotations, and see [Version Benchmarks](https://coralogix.com/docs/user-guides/monitoring-and-insights/version-benchmarks.md) for what the feature offers today.

## Permissions[​](#permissions "Direct link to Permissions")

* **View annotations**: requires access to the surface you're viewing (APM or Explore).
* **View version benchmark markers**: requires permission to view Version Benchmark tags (`VERSION-BENCHMARK-TAGS:READ`).
* **Send events**: use a **Send Your Data Key** with the **OpsEvents** role preset (see [Send events to Coralogix](#send-events-to-coralogix)).

## Related resources[​](#related-resources "Direct link to Related resources")

* [Annotations in APM](https://coralogix.com/docs/user-guides/apm-v2/features/annotations.md): scope annotations to a service and its related services.
* [Time-series chart](https://coralogix.com/docs/user-guides/data_exploration/timeseries-chart.md): the Explore chart that annotations overlay.
* [Version Benchmarks](https://coralogix.com/docs/user-guides/monitoring-and-insights/version-benchmarks.md): the version-tags feature that version benchmark markers come from.