Core Concepts

OpsTrails is built on a few simple ideas: events, timelines, and queries. Understanding these concepts will help you get the most out of the platform.

Events

An event represents a single, discrete moment in your infrastructure: a deployment, a rollback, a data load, an incident. Every event in OpsTrails follows the CloudEvents 1.0 specification, an industry standard for describing events.

Event Fields

Field	Type	Required	Description
`specversion`	string	required	Must be "1.0". Indicates CloudEvents specification version.
`type`	string	required	Event type, e.g. "deployment", "rollback", "data-load", "incident". Max 100 chars.
`source`	string	required	Event origin URI, e.g. "//github.com/org/repo". Max 500 chars.
`time`	string	required	Timestamp with timezone (ISO 8601/RFC 2822) or "NOW" for server time.
`id`	string	optional	Custom event ID. Auto-generated (UUID) if omitted. Max 200 chars.
`subject`	string	optional	Context label, e.g. "production", "staging", "server-01". Max 50 chars.
`severity`	string	optional	One of LOW, MINOR, MAJOR, CRITICAL.
`version`	string	optional	Release version, e.g. "1.2.3" or "v2.0.0-rc1". Max 50 chars.
`datacontenttype`	string	optional	MIME type of the data field. Defaults to "application/json". Max 200 chars.
`dataschema`	string	optional	URI pointing to the schema for the data field. Max 500 chars.
`data`	object	optional	Arbitrary JSON payload. Supports "description" (max 1000 chars), "timezone" (max 50 chars), and any extra fields.

Example Event

json

{
  "specversion": "1.0",
  "type": "deployment",
  "source": "//github.com/acme/api-service",
  "time": "2025-01-15T14:30:00Z",
  "id": "deploy-20250115-001",
  "subject": "production",
  "severity": "LOW",
  "version": "1.2.3",
  "data": {
    "description": "Deployed API service to production",
    "timezone": "Europe/London"
  }
}

Timeline

The timeline is the chronological history of all events in your organization. When you record an event, it's added to the timeline and becomes queryable immediately. The timeline gives your entire team a shared view of what happened across all infrastructure.

Event Types

The type field describes what kind of event occurred. You can use any string value. Common types include:

deployment — Code deployed to an environment
rollback — A deployment was reverted
release — A new version was released
incident — An incident was created or resolved
data-load — An ETL job or data migration completed
config-change — A configuration update was applied

Sources

The source field identifies where the event came from. It's a URI that typically follows the pattern //provider/org/repo:

//github.com/acme/api-service
//gitlab.com/acme/frontend
//jenkins/deploy-pipeline
//terraform/production-infra
//k8s/my-cluster/my-app

Subjects

The subject field provides context for the event. Most commonly it represents the target environment:

production, staging, development
us-east-1, eu-west-1
server-01, worker-pool-a

Severity Levels

The optional severity field indicates the impact level of the event:

LOW — Routine operations (standard deployments, scheduled data loads)
MINOR — Notable changes (configuration updates, non-critical rollbacks)
MAJOR — Significant changes (major version releases, large migrations)
CRITICAL — High-impact events (production incidents, emergency rollbacks)

📝 Note

Severity is optional. If omitted, the event will appear on the timeline without a severity indicator. Use it when you want to filter or prioritize events during investigation.

Time Format

The time field accepts:

"NOW" (case-insensitive) — Uses the current server time
ISO 8601 with timezone — 2025-01-15T14:30:00Z or 2025-01-15T14:30:00+02:00
RFC 2822 — Wed, 15 Jan 2025 14:30:00 +0200

⚠️ Warning

Bare datetimes without timezone (e.g. 2025-01-15T14:30:00) are rejected. Always include a timezone offset or use "NOW".

Previous← Quick Start NextAPI Reference →