# Event markers

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

When a metric shifts on a service page — error rate climbs, latency drifts, throughput drops — the next question is always "what changed?" Event markers put every dated change on the same timeline as your metrics: deployments, feature-flag changes, incidents, marketing campaigns, or any other event you send to Coralogix. The markers that landed around the shift tell you which change to investigate — on the chart itself, without switching tools.

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

* Access to APM and the service page for the service you want to analyze.
* Event markers ingested through the Coralogix ops-events ingest API. See [Send events to Coralogix](#send-events-to-coralogix).

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

You turn on event markers per service page or from the **Service Catalog**. The setting persists across sessions.

1. In your Coralogix toolbar, select **APM**, then **Service Catalog**.
2. Select the service you want to analyze.
3. In the header at the top of the service page, select the **Chart settings** button next to the time range picker.
4. In the **Chart settings** panel, turn on **Event markers**.

[![Chart settings button in the service-page header](/docs/assets/images/event-markers-125e5d08f25ef3d5f8ee4ecff68811a3.webp)](https://coralogix.com/docs/docs/assets/images/event-markers-125e5d08f25ef3d5f8ee4ecff68811a3.webp)

Markers appear as vertical annotations across every chart on the service page, aligned to event timestamps. Hover a marker to see its details — the source system, the event description, and the service and environment it applies to.

## Filter which events appear[​](#filter-which-events-appear "Direct link to Filter which events appear")

Under **Event markers**, select which markers to show:

* **Service events** (default): markers linked to this service.
* **Service and related events**: markers linked to this service and its related services. See [Related services](#related-services).
* **All events**: every event marker in your account. Events without a `service.name` — for example, account-wide incidents, marketing campaigns, or feature-flag changes — appear only under **All events**, alongside every service's deployment events.

Next to **Service and related events**, an **N services** link shows the count of related services included in the filter. Select it to open [Analyze](https://coralogix.com/docs/docs/user-guides/apm/features/analyze/.md), where you can inspect the services in the filter.

## Show or hide marker categories[​](#show-or-hide-marker-categories "Direct link to Show or hide marker categories")

On the chart, Coralogix groups markers by category and draws each in its own color, with a matching dashed entry in the chart legend. Deployment events sent as `cdEvent` appear under **Deployments**. Only categories that have events in the current time range appear in the legend. Select a category's legend entry to hide its markers, and select it again to show them.

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

Send event markers through the Coralogix ops-events ingest API. Coralogix stores each event as an `opsEvents` entity in the `default/ops.events` dataset, so you can query stored events in DataPrime.

The API is available both as gRPC and as REST (HTTP transcoding):

* **REST**: `POST /v1/ops-events`
* **gRPC**: `com.coralogixapis.opsevents.v1.OpsEventsIngestService/CreateOpsEvent`

Authenticate with a Coralogix `api_key_v2` in the `Authorization` header: `Authorization: Bearer <api_key_v2>`.

### Request body[​](#request-body "Direct link to Request body")

Wrap each event in an `opsEvent` object:

```
{

  "opsEvent": {

    "timestamp": "…",

    "description": "…",

    "attributes": { … },

    "cdEvent": { … }

  }

}
```

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

* `timestamp`: RFC 3339 timestamp for when the event happened. It must be within 24 hours of the current server time: the API rejects events dated more than 24 hours in the past or future, so send events as the deploy happens rather than backfilling older ones.
* `description`: a short, human-readable summary of the event, shown on hover in the UI. Must not be empty.
* An event object: you must include one. Currently `cdEvent` is the only supported kind; more kinds are added over time.

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

Add these to route the event to the right filters and to make the marker useful in the UI:

* `attributes.service.name`: links the event to a service. Events without this attribute appear **only** under the **All events** filter.
* `attributes.environment`: scopes the event to an environment (for example, `production`, `staging`).
* `cdEvent.system`: the CI/CD system that produced the event. One of `CD_SYSTEM_GITHUB`, `CD_SYSTEM_ARGOCD`, `CD_SYSTEM_JENKINS`.
* `cdEvent.pipeline.name`: pipeline name shown on hover.
* `cdEvent.pipeline.run.id`, `cdEvent.pipeline.run.url`: run identifier and deep link to the pipeline run.
* `cdEvent.pipeline.run.durationSeconds`: how long the pipeline run took, in seconds.
* `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`: repository name and clickable link.
* `cdEvent.vcs.ref.head.name`, `cdEvent.vcs.ref.head.revision`: branch or tag name and commit hash.

For events that do not describe a CD pipeline — account-wide incidents, marketing campaigns, feature-flag changes — add any custom keys under `attributes.additional`. Events without `attributes.service.name` are visible only under **All events**.

Stored events strip the enum prefix — `CD_SYSTEM_ARGOCD` becomes `argocd`, `PIPELINE_RESULT_STATUS_SUCCESS` becomes `success`, 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")

Send this with a current `timestamp` — the API rejects events dated more than 24 hours from the server time:

```
curl -X POST https://api.<coralogix-domain>/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",

            "durationSeconds": 145

          },

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

          "task": { "name": "deploy-to-production", "type": "PIPELINE_TASK_TYPE_DEPLOY" }

        },

        "vcs": {

          "system": "VCS_SYSTEM_GITHUB",

          "type": "VCS_REF_TYPE_BRANCH",

          "repository": {

            "name": "payments-platform",

            "url": "https://github.com/org/payments-platform"

          },

          "ref": {

            "head": {

              "name": "main",

              "revision": "abc123def456789abcdef0123456789abcdef01"

            }

          }

        }

      }

    }

  }'
```

A successful request returns the server-generated event `id`.

For the full schema, per-language SDK examples, and Terraform provider usage, see the ops-events ingest API reference in the developer portal (in progress).

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

A related service is a service that sends requests to the current service or receives requests from it. Coralogix derives the set from the [Service Map](https://coralogix.com/docs/docs/user-guides/apm/features/service-map/.md).

When you select **Service and related events**, the filter includes:

* The current service: the service the page is for.
* Every service in that service's Service Map neighborhood.

## Limitations[​](#limitations "Direct link to Limitations")

* Only `cdEvent` (continuous delivery events) is a validated event type today. Custom event kinds ingest through the same API — they land in the `ops.events` dataset and appear on charts, but do not benefit from the CD-specific fields (pipeline metadata, VCS deep links).
* The **N services** link next to **Service and related events** opens Analyze in a new tab. A later release deep-links directly to the Service Map section within Analyze.

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

* [Service Map](https://coralogix.com/docs/docs/user-guides/apm/features/service-map/.md): how Coralogix builds the service dependency graph that defines related services.
* [Group by service version](https://coralogix.com/docs/docs/user-guides/apm/features/group-by-service-version/.md): compare metrics across the deployments an event marker represents.
* [OpenTelemetry CI/CD semantic conventions](https://opentelemetry.io/docs/specs/semconv/registry/attributes/cicd/): the OTel conventions that inspired the `cdEvent` field names.