Events

Every check execution, alert state transition, and derived signal in Yorker becomes an event. Events are the unit of currency for the dashboard timeline, the OTel emission layer, and the /api/events query interface. This page explains where events come from, what catalog of types exists, and how to query them.

Two sources

Yorker materializes events from two underlying tables:

The unified /api/events endpoint reads from both, merges by timestamp, and applies pagination so consumers see one stream.

A single MCP check run can emit two events from one check_results row: the success/failure event and a check.mcp_schema_drift event when the run detected a tool list or signature change. The two events share the same top-level traceId and the same synthetics.run.id inside resourceAttributes, so a consumer can correlate them.

Relation to OTel emission

The events stream you see in the dashboard and via /api/events is the same set of facts Yorker also emits to your configured OTel collector. The two surfaces serve different audiences:

Derived events (incident lifecycle, certificate observations, SLO burn warnings, deployment markers, maintenance windows, cross-monitor correlation) are produced by the control plane and shipped to your collector via the orchestrator outbox. They do not appear under /api/events today; that endpoint is scoped to check executions and alert state transitions. To see derived events, query your OTel backend (HyperDX, ClickStack, Grafana, etc.).

For the architecture of the two emission paths (runner-direct vs control-plane outbox), see Architecture > Telemetry flow.

The full OTel event catalog

When a team OTLP endpoint is configured, Yorker emits the events below as OTLP log records via the outbox. Resource attributes vary by event scope:

• Check-scoped events (synthetics.check.completed, synthetics.check.failed, synthetics.step.completed, synthetics.mcp.schema_drift, synthetics.tls.*, synthetics.correlation.detected) carry synthetics.check.id, synthetics.check.name, synthetics.check.type (and url.full when known) as resource attributes. synthetics.run.id, synthetics.location.id, synthetics.location.name, and synthetics.check.status are emitted as LogRecord attributes, not resource attributes.
• Alert events (synthetics.alert.state_changed) carry service.name = "synthetics" plus synthetics.check.name (always emitted; the upstream alert pipeline requires a non-null check name) and synthetics.check.id (when set on the alert) as resource attributes. They are linked to a check, but they don't carry the full per-check resource set (no synthetics.check.type, no location attrs at the resource level).
• Team-scoped events (synthetics.deployment.created, synthetics.maintenance_window.*, synthetics.incident.*, synthetics.slo.budget.warning) carry only service.name = "synthetics" plus event-specific identifiers as LogRecord attributes; they are not bound to a single check.

Event-specific attributes are inlined in the OpenTelemetry concepts page for the cross-monitor correlation event. For other events, the simplest path is to query a sample row in your OTel backend and inspect the attribute set, or grep the source: apps/web/src/lib/otel-events.ts for check, step, MCP drift, TLS, deployment, maintenance, SLO, incident, and correlation events; apps/web/src/lib/otel-emit.ts for the alert state-changed event.

See OpenTelemetry concepts for the standard set of identifying attributes Yorker emits across signals, and for the dedicated attribute reference for the cross-monitor correlation event. Note that the OpenTelemetry page describes the metrics/traces emission shape (where check, location, run, and labels are all on resource attributes); the log-event outbox path documented above splits those across resource attributes (check identifiers) and LogRecord attributes (run, location, status). Team-scoped log events (deployment, maintenance, incident, SLO burn) carry a smaller resource set centred on service.name.

Querying via /api/events

The unified events endpoint returns check and alert events in a single time-ordered stream. See REST API > Events for the full schema.

curl 'https://yorkermonitoring.com/api/events?range=24h&limit=50' \
  -H "Authorization: Bearer sk_..."

{
  "events": [
    {
      "id": "res_xyz789",
      "eventType": "check.completed",
      "timestamp": "2026-05-14T10:05:00.142Z",
      "checkId": "chk_abc123",
      "checkName": "Homepage",
      "checkType": "http",
      "severity": null,
      "traceId": "4bf92f3577b34da6a3ce929d0e0e4736",
      "summary": "142 ms",
      "resourceAttributes": {
        "synthetics.check.id": "chk_abc123",
        "synthetics.check.name": "Homepage",
        "synthetics.check.type": "http",
        "synthetics.run.id": "run_abc",
        "synthetics.location.id": "loc_us_east",
        "synthetics.location.name": "US East (Ashburn)"
      },
      "attributes": {
        "synthetics.http.response_time": 142,
        "synthetics.check.success": 1,
        "synthetics.http.status_code": 200
      }
    }
  ],
  "limit": 50,
  "offset": 0,
  "hasMore": true
}

Filters

Event shape

Every event returned by /api/events has the same envelope:

The keys here are stable across /api/events calls but they don't all match the OTLP LogRecord attribute names emitted by the outbox path: for example /api/events carries synthetics.http.response_time while OTLP LogRecords use synthetics.response_time_ms, and /api/events carries synthetics.http.status_code while OTLP uses http.response.status_code. Plan to translate keys when reusing query logic across the two surfaces. The single source of truth is apps/web/src/app/api/events/route.ts for /api/events and packages/shared/src/constants/otel.ts (OTEL_ATTRS) for the OTLP path.

Pagination

Within each source (check executions, alert events) the endpoint orders by (timestamp DESC, id DESC) so a single source paginates stably even when two rows share a millisecond. The merged stream returned to the caller sorts by timestamp only; two events from different sources that share a millisecond can swap order across pages. hasMore: true means at least one more event exists past offset + limit. To page through, increment offset by the page size; once offset > 10000 the handler returns 400, so narrow the time range and start a fresh paging cycle instead.

Deployment markers

Recording a deployment marker is a write-side concern that lives at the same prefix as the read-side feed:

curl -X POST https://yorkermonitoring.com/api/events/deployments \
  -H "Authorization: Bearer sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "service": "checkout-api",
    "version": "v2.18.0",
    "environment": "production",
    "commit_sha": "a1b2c3d4",
    "commit_message": "fix: retry idempotency",
    "deployed_by": "drewpost",
    "source": "github-actions"
  }'

The POST body uses snake_case field names (commit_sha, commit_message, deployed_by) for CI-friendliness. The GET response side uses camelCase to match the rest of the read API. Both are documented in REST API > Deployment Events.

A deployment marker becomes a synthetics.deployment.created OTLP event (when an OTel endpoint is configured) and a row in deployment_events that the dashboard correlates with check-result anomaly windows.

Where events surface

If you need to slice events by attribute (e.g., "all check.failed from loc_eu_west in the last hour"), the OTel backend is the right surface; /api/events filters are limited to the columns above. Trace correlation works in both directions: the traceId on every event links back to the originating check execution span and out to your backend's distributed trace view.