Event Markers

What Are Event Markers?

Event markers let you annotate your ApiTraffic dashboard with significant moments — deployments, incidents, configuration changes, scaling events — so you can visually correlate them with changes in your API’s throughput, error rates, and response times. When an event is created, it appears as a vertical line on your Throughput and Response Time charts, making it immediately obvious whether a deploy caused a latency spike or an incident coincided with a drop in traffic.

Why Use Event Markers?

Without event markers, correlating API behavior changes with infrastructure events means switching between dashboards, CI/CD logs, and incident timelines. Event markers bring all of that context into one view:

Post-deploy verification — Did error rates increase after the last release?
Incident correlation — When did the degradation start relative to the config change?
Performance tracking — Did the scaling event actually improve response times?
Team visibility — Everyone on the team can see what changed and when, without digging through deploy logs.

Event Types

Type	When to use
`deployment`	Code releases, rollbacks, container image updates
`incident`	Outages, degradations, alerts firing
`config_change`	Feature flag toggles, environment variable updates, DNS changes
`scale`	Autoscaling events, manual instance scaling, database upgrades
`custom`	Anything else worth tracking

Creating Events

There are three ways to create events, depending on your workflow.

From the Dashboard

Navigate to Account → Events in the left sidebar and click Create Event. This is useful for manually logging incidents or one-off events. You can set:

Type and Name (required)
Description and Source (optional context)
Buckets and Environments (scope the event or apply to all)
Started At and Ended At (defaults to now if left blank)

From Your CI/CD Pipeline

The most powerful use of events is automated creation from your deployment pipeline. By adding a single API call to the end of your deploy job, every release is automatically tracked on your charts. You’ll need:

Your Account SID (found in Account Settings)
An API Token (create one under Account → API Tokens)

Store both as secrets/environment variables in your CI/CD platform.

name: Deploy
on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      # ... your existing deploy steps ...

      - name: Create ApiTraffic Deploy Event
        if: success()
        run: |
          curl -s -X POST \
            "https://api.apitraffic.io/v1/accounts/${{ secrets.APITRAFFIC_ACCOUNT_SID }}/events" \
            -H "Authorization: Bearer ${{ secrets.APITRAFFIC_API_TOKEN }}" \
            -H "Content-Type: application/json" \
            -d '{
              "type": "deployment",
              "name": "${{ github.ref_name }} @ ${{ github.sha }}",
              "description": "Deployed by ${{ github.actor }}",
              "source": "github_actions",
              "metadata": {
                "commitSha": "${{ github.sha }}",
                "branch": "${{ github.ref_name }}",
                "actor": "${{ github.actor }}",
                "runId": "${{ github.run_id }}",
                "runUrl": "${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}"
              }
            }'

From an AI Assistant (MCP)

If you have an MCP token configured, AI assistants connected to ApiTraffic can create events using the create_event tool. This is useful for logging events conversationally:

“Create a deployment event for v2.3.1 release on the production bucket”

The MCP server also exposes list_events for querying existing events.

Scoping Events to Buckets & Environments

By default, events apply to all buckets and all environments (represented as ["*"]). This means the event annotation will appear on every dashboard. If your event only affects a specific service or environment, you can scope it:

{
  "type": "deployment",
  "name": "payments-service v1.4.2",
  "bucketSids": ["bkt_abc123def456ghi789jkl012"],
  "environmentSids": ["env_prod789uvw012rst345abc"]
}

Scoped events only appear on the matching bucket/environment dashboard, keeping charts clean and relevant.

When using the dashboard UI to create events, toggle off “Apply to all” under Buckets or Environments to select specific targets.

The Metadata Field

The metadata field accepts any JSON object. Use it to store context that helps you trace from a chart annotation back to the exact change:

{
  "metadata": {
    "commitSha": "a1b2c3d4e5f6",
    "branch": "main",
    "imageTag": "v2.3.1",
    "prNumber": 427,
    "prUrl": "https://github.com/org/repo/pull/427",
    "rollback": false
  }
}

This data is stored with the event and returned in list/get API responses, making it available for auditing and automation.

Point-in-Time vs Duration Events

Point-in-time events have only a startedAt timestamp (or leave it blank to default to “now”). These are ideal for deploys, config changes, and scaling events — things that happen at a specific moment. Duration events have both startedAt and endedAt timestamps. These are ideal for incidents:

{
  "type": "incident",
  "name": "Database connection pool exhaustion",
  "startedAt": "2024-01-15T14:00:00Z",
  "endedAt": "2024-01-15T14:45:00Z"
}

You can create an incident event when it starts (without endedAt), then update it with the resolution time later using the Update Event API endpoint.

Managing Events

Navigate to Account → Events in the dashboard to view, create, and delete events. The table shows:

Type — color-coded badge
Name — event title
Source — where the event came from
Started At — when it occurred
Actions — delete events you no longer need

For programmatic management, see the full Events API Reference.

Best Practices

Automate Everything

The most valuable events are the ones you don’t have to remember to create. Add event creation to every deploy pipeline, every scaling automation, and every incident bot.

Use Descriptive Names

Include version numbers, service names, or ticket IDs so events are meaningful at a glance on the chart:

payments-service v2.3.1
feature-flag: dark-mode enabled
INCIDENT-1234: API gateway timeout

Store Rich Metadata

Commit SHAs, PR links, Docker image tags, and pipeline URLs make it trivial to trace from a traffic anomaly to the exact change that caused it.

Scope When Possible

If a deploy only touches one service, scope the event to that bucket. This keeps other dashboards uncluttered and makes the correlation signal stronger.

Close Your Incidents

When an incident is resolved, update the event with endedAt and a resolution description. This creates a clear record of impact duration.

Standardize Source Names

Pick consistent source identifiers across your team and pipelines:

Source	Use for
`github_actions`	GitHub Actions workflows
`gitlab_ci`	GitLab CI/CD pipelines
`jenkins`	Jenkins jobs
`circleci`	CircleCI workflows
`argocd`	Argo CD sync events
`manual`	Events created from the dashboard UI
`mcp`	Events created via AI assistant

Get Started

Features

Integrations

What Are Event Markers?

Why Use Event Markers?

Event Types

Creating Events

From the Dashboard

From Your CI/CD Pipeline

From an AI Assistant (MCP)

Scoping Events to Buckets & Environments

The Metadata Field

Point-in-Time vs Duration Events

Managing Events

Best Practices

Automate Everything

Use Descriptive Names

Store Rich Metadata

Scope When Possible

Close Your Incidents

Standardize Source Names

What’s Next?

Events API Reference

MCP Server

Get Started

Features

Integrations

​What Are Event Markers?

​Why Use Event Markers?

​Event Types

​Creating Events

​From the Dashboard

​From Your CI/CD Pipeline

​From an AI Assistant (MCP)

​Scoping Events to Buckets & Environments

​The Metadata Field

​Point-in-Time vs Duration Events

​Managing Events

​Best Practices

​Automate Everything

​Use Descriptive Names

​Store Rich Metadata

​Scope When Possible

​Close Your Incidents

​Standardize Source Names

​What’s Next?

Events API Reference

MCP Server

What Are Event Markers?

Why Use Event Markers?

Event Types

Creating Events

From the Dashboard

From Your CI/CD Pipeline

From an AI Assistant (MCP)

Scoping Events to Buckets & Environments

The Metadata Field

Point-in-Time vs Duration Events

Managing Events

Best Practices

Automate Everything

Use Descriptive Names

Store Rich Metadata

Scope When Possible

Close Your Incidents

Standardize Source Names

What’s Next?