# 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/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. [![Deployment markers as dashed vertical lines across the service-page charts, with a hover tooltip showing the deployment name, service, and environment](/docs/assets/images/event-markers-live-24b15fa2f839019ed601811573bacae5.webp)](https://coralogix.com/docs/assets/images/event-markers-live-24b15fa2f839019ed601811573bacae5.webp) *Deployment markers line up across every chart on the service page. Hovering a marker shows its details, here, a `product-catalog` deployment to the `otel-demo` environment.* ## 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/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. [![Explore view with the default/ops.events dataset selected as the source, listing ingested events](/docs/assets/images/events-in-explore-fa8e8f6bda0310c8f9ec94da2f49ed65.webp)](https://coralogix.com/docs/assets/images/events-in-explore-fa8e8f6bda0310c8f9ec94da2f49ed65.webp) *Every event you send through the ops-events API lands in the `default/ops.events` dataset. Set it as the source in Explore to view your markers as a table and query them with 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 **Send Your Data Key** in the `Authorization` header: `Authorization: Bearer `. 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**, which covers logs, metrics, and traces) is rejected with `403 Forbidden`. ### 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, either `cdEvent` for CI/CD deploys or `customEvent` for a generic marker. More typed 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) send a `customEvent` instead of a `cdEvent`. A `customEvent` carries no fields of its own: put the summary in `description` and any structured data under `attributes.additional`. As with any event, one sent without `attributes.service.name` is 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") Set `$CX_API_KEY` to a **Send Your Data Key** that has the **OpsEvents** role preset, any other key type or preset returns `403 Forbidden`. Send this with a current `timestamp`, the API rejects events dated more than 24 hours from the server time: ``` curl -X POST https://api./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`. ### 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./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": {} } }' ``` This event has no `attributes.service.name`, so it appears only under the **All events** filter. 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/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") * Event markers support two event kinds today: `cdEvent` for continuous-delivery events (with pipeline and VCS metadata) and `customEvent` for generic markers. Both appear on charts; only `cdEvent` carries the CD-specific fields. More structured kinds are added over time. * 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/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/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.