Getting Started — “I’m In, Now What?”

You have signed up, you are in the dashboard — now what? This guide walks you through the process of planning your event model, sending your first events, and teaching the AI assistant about your infrastructure. By the end you will have a working setup and an AI that understands your system.

The Big Picture — Your Infrastructure as a Grid

Before diving into individual fields, it helps to have a mental model of how OpsTrails sees your infrastructure. Think of it as a grid with two axes:

• Horizontal — environments (subject): the progression of your deployment targets from left to right. Development, staging, production. The same system replicated across different stages.
• Vertical — systems (source): the stack of components within any single environment. Frontend, backend, database, cache. The depth of your architecture.

              DEVELOPMENT     STAGING       PRODUCTION
           ┌──────────────┬──────────────┬──────────────┐
  FE       │              │              │              │
           ├──────────────┼──────────────┼──────────────┤
  BE       │              │   ★ deploy   │              │
           ├──────────────┼──────────────┼──────────────┤
  DB       │              │              │              │
           ├──────────────┼──────────────┼──────────────┤
  CACHE    │              │              │              │
           ├──────────────┼──────────────┼──────────────┤
  WORKER   │              │              │              │
           └──────────────┴──────────────┴──────────────┘

Every event you send lands at a specific intersection on this grid. The star above represents “the backend was deployed to staging” — source: "BE", subject: "STAGING". The type field then tells you what happened at that intersection (a deployment, a rollback, a config change), and severity tells you how significant it was.

Step 1 — Understand the Event Payload

Every event you send to OpsTrails follows the CloudEvents 1.0 specification. Before you fire off your first curl, it helps to understand what each field does and how OpsTrails uses it.

Here is a complete event payload with every available field:

{
  "specversion": "1.0",
  "type": "deployment",
  "source": "//github.com/acme/api-service",
  "time": "NOW",
  "id": "deploy-20250115-001",
  "subject": "production",
  "severity": "MAJOR",
  "version": "2.4.0",
  "datacontenttype": "application/json",
  "dataschema": "https://example.com/schemas/deploy.json",
  "data": {
    "description": "Quarterly release with new checkout flow",
    "timezone": "Europe/London",
    "ticket": "JIRA-1234",
    "deployer": "jane.doe"
  }
}

Required fields

Optional fields

Step 2 — Define Your Environments

The subject field represents where in your infrastructure something happened. Think of it as your environment identifier — the horizontal axis of the grid. Before sending events, sit down and map out your environments.

Simple setup

Most teams have a straightforward environment ladder:

PRODUCTION
STAGING
DEVELOPMENT
LOCAL

If this matches your setup, you are ready — use these values directly in the subject field.

Multi-brand / multi-entity setup

If your organization operates multiple brands, websites, or business units that each have their own environment ladder, encode that into the subject. Use a consistent delimiter (a hyphen works well):

BRAND-A-PRODUCTION
BRAND-A-STAGING
BRAND-A-DEVELOPMENT
BRAND-B-PRODUCTION
BRAND-B-STAGING
BRAND-B-DEVELOPMENT

This pattern also applies to multi-region or multi-tenant setups:

US-PRODUCTION          TENANT-ACME-PRODUCTION
US-STAGING             TENANT-ACME-STAGING
EU-PRODUCTION          TENANT-GLOBEX-PRODUCTION
EU-STAGING             TENANT-GLOBEX-STAGING
APAC-PRODUCTION

Advanced: sub-environments

In some systems — particularly those with content management workflows — environments have sub-environments that represent content states or approval stages:

BRAND-A-DEVELOPMENT-EDITOR
BRAND-A-DEVELOPMENT-PREVIEW
BRAND-A-DEVELOPMENT-APPROVED
BRAND-A-STAGING-EDITOR
BRAND-A-STAGING-APPROVED
BRAND-B-PRODUCTION-LIVE
BRAND-B-PRODUCTION-PREVIEW

This is less common but fully supported. OpsTrails places no restrictions on how you structure the subject — it is a free-form string (up to 50 characters).

Step 3 — Define Your Sources

The source field represents what system produced the event. If subject is the horizontal axis of your infrastructure (environments), source is the vertical axis (systems within those environments).

Think about all the distinct systems that make up your platform:

You can also use more descriptive names or URIs. The CloudEvents spec suggests a URI format:

//github.com/acme/api-service
//github.com/acme/frontend
//jenkins/deploy-pipeline
//terraform/production-infra

Either approach works. Short identifiers like FE and BE are easier to type in curl commands. URI-style sources are more precise when you have many repositories. You do not need to capture all systems on day one — you can add sources as you go.

Step 4 — Define Your Event Types

The type field describes what kind of operation happened. Common event types include:

You can use any string here. Choose names that your team already uses when talking about operations — if you say “we did a deploy”, use deployment. If you say “we pushed a hotfix”, you might use hotfix or just deployment with a description in data.

Step 5 — Decide on Severity Usage

Severity is optional but useful. It tells OpsTrails (and the AI assistant) how significant an operation is. There are four levels:

A practical approach: start simple. Only set severity on production events. A deploy to staging does not need a severity tag. A major release to production benefits from MAJOR or CRITICAL.

Step 6 — Send Your First Events

You have planned your environments, sources, types, and severity conventions. Now send a real event. Go to Settings → API Keys in the dashboard and create a key with READ_WRITE scope. Copy the key — it is only shown once.

Minimal event

curl -X POST https://api.opstrails.dev/api/v1/events \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "specversion": "1.0",
    "type": "deployment",
    "source": "BE",
    "time": "NOW"
  }'

Event with environment and context

curl -X POST https://api.opstrails.dev/api/v1/events \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "specversion": "1.0",
    "type": "deployment",
    "source": "BE",
    "time": "NOW",
    "subject": "PRODUCTION",
    "severity": "MAJOR",
    "version": "2.4.0",
    "data": {
      "description": "Quarterly release with new checkout flow and payment provider migration",
      "ticket": "JIRA-1234"
    }
  }'

Verify it worked

Switch to the Events tab in the dashboard. Your event should appear in real time — no refresh needed. The live feed updates automatically as events arrive.

Try sending a few more events with different types and sources to build up some data:

# A frontend deployment
curl -X POST https://api.opstrails.dev/api/v1/events \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "specversion": "1.0",
    "type": "deployment",
    "source": "FE",
    "time": "NOW",
    "subject": "STAGING",
    "version": "1.8.0",
    "data": {
      "description": "Updated landing page with new hero section"
    }
  }'

# A database migration
curl -X POST https://api.opstrails.dev/api/v1/events \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "specversion": "1.0",
    "type": "db-migration",
    "source": "DB",
    "time": "NOW",
    "subject": "PRODUCTION",
    "severity": "MAJOR",
    "data": {
      "description": "Added indexes on orders table for reporting queries"
    }
  }'

# A cache purge
curl -X POST https://api.opstrails.dev/api/v1/events \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "specversion": "1.0",
    "type": "cache-purge",
    "source": "CACHE",
    "time": "NOW",
    "subject": "PRODUCTION",
    "severity": "LOW"
  }'

Step 7 — Teach the AI About Your Infrastructure

You have events flowing in. The AI assistant can already see them, but it does not understand what FE, BE, or BRAND-A-PRODUCTION means in your context. You need to give it that understanding.

Go to Settings and find the Business Context section:

What to include

Write a few paragraphs covering:

1. What your organization does — one or two sentences so the AI has business context.
2. Your environment naming convention — explain what each subject value means.
3. Your sources — explain what each system is and what role it plays.
4. Your event types — explain what operations each type represents. Mention if certain types on certain environments carry special significance (e.g. “a deployment to a PRODUCTION subject is a release”).
5. Severity conventions — if you use severity, explain your thresholds.
6. Anything else — deployment windows, tightly coupled systems, team structure.

Example business context

Here is an example for a fictional e-commerce company with two brands:

We are an e-commerce company operating two brands: ShopMax and BuyFast.

ENVIRONMENTS:
Each brand has its own environment ladder. Environment subjects follow the
pattern BRAND-ENVIRONMENT:
- SHOPMAX-PRODUCTION — live customer-facing environment for ShopMax
- SHOPMAX-STAGING — pre-production testing for ShopMax
- SHOPMAX-DEVELOPMENT — development environment for ShopMax
- BUYFAST-PRODUCTION — live customer-facing environment for BuyFast
- BUYFAST-STAGING — pre-production testing for BuyFast
- BUYFAST-DEVELOPMENT — development environment for BuyFast

A deployment to any PRODUCTION environment is considered a release.

SOURCES:
- FE — frontend React application (Next.js), serves the storefront
- BE — backend API service (Node.js), handles orders, payments, inventory
- DB — PostgreSQL database, shared across brands
- CACHE — Cloudflare edge cache, handles product pages and static assets
- CMS — headless CMS (Contentful), manages product descriptions and pages
- WORKER — background job processor, handles email, inventory sync, reports

TYPES:
- deployment — code deployed to an environment
- rollback — a deployment that was reverted
- db-migration — database schema change applied
- cache-purge — CDN/edge cache invalidated
- content-publish — content updated via CMS
- config-change — environment variables or feature flags updated
- incident — an incident was opened or resolved (check data.description)

SEVERITY:
We mark production deployments as MAJOR by default. Hotfixes and incidents
are CRITICAL. Everything else is LOW or MINOR.

NOTES:
- BE and DB deployments are tightly coupled — a backend deployment often
  includes a database migration. If you see issues after a BE deployment,
  check for a recent DB event as well.
- We deploy to staging before production. A missing staging deployment
  before a production deployment is unusual and worth flagging.
- Deployments happen during business hours (9:00–18:00 CET) on weekdays.
  Anything outside that window is either a hotfix or an incident response.

Why this matters

Without business context, the AI treats your events as raw data. With business context, it can:

• Correlate events intelligently — “the backend deployment 5 minutes before the error spike is likely related”
• Flag anomalies — “this production deployment happened outside your usual deployment window”
• Understand severity — “this was marked CRITICAL, which in your convention means a hotfix or incident response”
• Speak your language — “the ShopMax frontend was deployed to staging” instead of “an event with source FE and subject SHOPMAX-STAGING”

Step 8 — Query With the AI

Once you have events and business context in place, you can use OpsTrails through any AI assistant that supports MCP (Model Context Protocol) — Claude, Cursor, Claude Code, and others.

Connecting your AI assistant

OpsTrails provides an MCP endpoint at:

https://api.opstrails.dev/api/mcp/mcp

Your AI assistant connects to this endpoint using a READ_ONLY or READ_WRITE API key. Configuration varies by client — check the MCP section for setup instructions specific to your tool.

Example queries

Once connected, you can ask questions in natural language:

• “What was deployed in the last 2 hours?”
• “Show me all production deployments today”
• “What changed in the ShopMax backend since yesterday?”
• “Was there anything deployed right before the error spike at 2pm?”
• “Give me a summary of today’s activity”
• “List all sources that have reported events this week”

The AI uses the business context you wrote in Step 7 to interpret and explain the results in terms that make sense for your organization.

Recap

You are now set up. From here, the next steps are to integrate event tracking into your CI/CD pipeline (see the docs on GitHub Actions, SDK, and CLI) and optionally connect analytics providers for before/after metric comparisons around events.