Deployments.ai Docs

Event analytics

Query every semantic event the platform publishes with Athena, from a script or an MCP server: what the log records, how it is delivered, what it costs, and how operators get access.

Event analytics keeps a queryable history of every semantic event the installation publishes, across all tenants, for the people who operate the platform. A projector Lambda copies each event from the platform's EventBridge bus into an Apache Iceberg table in S3 Tables, and operators query that table with Athena through bun run events or a local MCP server. The modules are infrastructure/modules/event-analytics and the table in infrastructure/modules/platform-data.

Operator-only data

The event log holds every organization's events, with their payloads. It has no tenant boundary: anyone who can query it sees all tenants. Grant access only to platform operators, and do not expose the script or the MCP server to tenants or to agents that act for them.

Availability

The customer root runs event analytics by default. The deploy tool builds and publishes the projector with every release, so a default installation needs no input for it.

What it records

The log has one row per delivery of each event with the source deployments-ai.platform: resource changes such as an organization, project, agent, or run being created, updated, or deleted, and the channel and provider events. It also records the sources listed in event_analytics_extra_sources (see Record other sources). Each row carries the event's canonical fields and its payload as JSON:

ColumnWhat it holds
event_idThe event's ULID. One event keeps one ID however often it is delivered.
event_type, event_entity, event_actionThe dotted type, such as agent.created, and its parts before and after the dot.
organization_id, project_id, environment_idThe tenant scope. Project and environment are empty when the event has none.
aggregate_type, aggregate_id, aggregate_versionThe resource that changed and its version after the change.
actor_type, actor_idWho caused the change, when the platform knows.
trace_idThe trace of the request that caused it.
occurred_at, ingested_atISO 8601 strings: when the change happened and when EventBridge accepted it.
eventbridge_event_id, eventbridge_detail_typeThe EventBridge delivery, which differs for each redelivery.
event_source, aws_account_id, aws_regionWhere the event came from.
payload_jsonThe event payload.

bun run events -- schema prints the same list. The table is not partitioned, so every query scans it whole; filters reduce the rows returned, not the bytes scanned.

How it differs from observability and webhooks

SurfaceHoldsWho reads it
Event analyticsEvery semantic event of every tenantPlatform operators, with Athena SQL
ObservabilityExecution facts: traces, spans, usage, and metricsEach tenant through the API and console
WebhooksThe same semantic events, pushed to an environment's subscriptions as they happenEach tenant's own HTTPS endpoints

Use event analytics to answer questions about the platform as a whole, such as which event types are busiest or what happened to one resource over time. Tenants never reach it.

Components

ComponentWhat it is
RuleThe EventBridge rule event-analytics-projector on the platform bus. It retries for 24 hours, then sends the event to the queue event-analytics-projector-dlq.
ProjectorThe Lambda function event-analytics-projector, Node.js 26 on ARM64. It validates each event against the canonical schema and writes one row to Firehose.
Firehose streamsemantic-events, which commits rows to the Iceberg table every 60 seconds or 5 MiB. Rows it cannot write land in the bucket event-analytics-backup-<account-id>.
Iceberg tablesemantic_events.events in the S3 Tables bucket semantic-events. platform-data creates it with every installation and protects it from deletion under operations.deletion_protection.
Athena workgroupsemantic-events. It enforces its result location, the bucket event-analytics-athena-<account-id>, and stops any query that scans more than 10 GiB. It holds two saved queries.
Operator policyThe managed IAM policy event-analytics-operator-query, which grants the read-only access below.
AlarmsSix CloudWatch alarms on projector errors, the dead-letter queue, dead-letter delivery failures, Firehose freshness, and rejected rows. They notify the ops alerts topic.

The root outputs event_analytics_athena (region, workgroup, catalog, database, table, and result location) and event_analytics_operator_query_policy_arn.

Delivery and duplicates

Delivery is at least once. EventBridge and the projector retry failures, and the event dispatcher can publish an event again, so one event_id can appear on more than one row. Every row of one event carries the same fields except eventbridge_event_id and ingested_at.

Count or list each event once:

  • Count with count(DISTINCT event_id).
  • To keep whole rows, rank each event's rows and keep the first:
WITH ranked AS (
  SELECT *, row_number() OVER (
    PARTITION BY event_id
    ORDER BY ingested_at DESC, eventbridge_event_id DESC
  ) AS delivery_rank
  FROM events
)
SELECT * FROM ranked WHERE delivery_rank = 1

recent, counts, and their MCP tools apply this already; your own SQL must do it. A new event is queryable about one to two minutes after it happens, once Firehose commits its buffer.

Lifecycle

event_analytics_lifecycle in infrastructure/environments/customer controls the stack. The Iceberg table and its history do not depend on it.

ValueEffect
runningThe default. The rule sends every new event to the projector.
stoppedRecords events exactly as running does.
absentNo stack. Valid only before the stack has ever been created.
decommissioningDisables the rule and prepares the failure and result buckets and the workgroup for deletion.
destroyedDeletes the stack after a successful decommissioning apply. It is final.

Record other sources

A product built on the installation can keep its own events in the same log. List its EventBridge sources in event_analytics_extra_sources in infrastructure/environments/customer, for example ["acme.orders"]. The rule then matches those sources as well as deployments-ai.platform, and event_source tells them apart in queries.

The publisher puts its events on the bus named by the root output semantic_event_bus_name, which needs events:PutEvents on that bus. Each event must look like a platform event:

  • detail is a canonical semantic event: ULID eventId, organizationId, and aggregateId, aggregateType, a positive aggregateVersion, eventType, an RFC 3339 occurredAt, and an object payload, with optional projectId, environmentId, actor, and traceId.
  • detail-type equals detail.eventType.

The projector rejects any other event; after retries it lands in the dead-letter queue and raises the DLQ alarm. Only event analytics matches the extra sources. Webhooks, workflows, and the other platform consumers still match deployments-ai.platform alone.

Athena, through bun run events or the MCP server, is the only query path. Tenants read their own execution data through observability, not this log.

Cost

Idle, event analytics costs about $0.60 a month: its six CloudWatch alarms at $0.10 each. Everything else bills by use:

PartBilled by
ProjectorLambda requests and duration, one invocation per event.
FirehoseData ingested into the Iceberg table.
Iceberg tableS3 Tables storage, requests, and automatic compaction. The table exists with or without the stack.
QueriesAthena data scanned, at least 10 MB per query and at most 10 GiB, plus result objects in S3.
Logs, queue, and GlueCloudWatch Logs ingestion, SQS requests, and Glue Data Catalog requests.

Publishing to the EventBridge bus is already paid by the event dispatcher; the extra rule adds no charge. Check current prices on the AWS pricing pages.

Operator access

Operators query with their own AWS credentials. Attach the policy named by event_analytics_operator_query_policy_arn to an operator role or permission set. It grants:

AccessActionsResource
Run queriesathena:StartQueryExecution, GetQueryExecution, GetQueryResults, StopQueryExecution, GetWorkGroupThe semantic-events workgroup
Read the catalogglue:GetCatalog, GetCatalogs, GetDatabase, GetDatabases, GetTable, GetTablesThe Glue Data Catalog
Read the tables3tables:GetTableBucket, GetNamespace, ListNamespaces, ListTables, GetTable, GetTableData, GetTableMetadataLocationThe semantic-events table bucket and its table
Write resultss3:GetBucketLocation, ListBucket, GetObject, PutObject, ListMultipartUploadParts, AbortMultipartUploadThe event-analytics-athena-<account-id> bucket

The S3 Tables catalog grants IAM_ALLOWED_PRINCIPALS, so IAM alone controls access and no Lake Formation grant is needed. Reading the root's outputs with --root also needs read access to its OpenTofu state.

Query from the command line

Run the script from a checkout of this repository with operator credentials in the environment:

export AWS_PROFILE=platform-operator AWS_REGION=us-east-2
bun run events -- recent
bun run events -- recent --organization <organization-id> --type 'agent.*' --since 7d --limit 20
bun run events -- counts --since 24h
bun run events -- sql "SELECT event_action, count(DISTINCT event_id) AS events FROM events GROUP BY 1"
bun run events -- sql --file query.sql --max-rows 500 --json
bun run events -- schema
CommandWhat it does
recentThe newest events, one row per event_id. --payload adds payload_json.
countsDistinct events per event type, busiest first.
sql <query>One read-only statement. The table is events; --file reads the statement from a file.
schemaThe columns and how to query them. Runs no query.

recent and counts filter with --organization, --type (end it with * to match a prefix), --since and --until (30m, 24h, 7d, or an ISO 8601 date or time; the window defaults to the last 24 hours), and --limit. Output is a table; --json prints the rows, the SQL that ran, the bytes scanned, and the query ID. Every command returns at most 1,000 rows and says when it cut rows off.

The script finds the table in this order: flags, then DEPLOYMENTS_AI_EVENT_ANALYTICS_<NAME> environment variables, then the event_analytics_athena output of the root that --root names, then the names every installation uses. --region and DEPLOYMENTS_AI_EVENT_ANALYTICS_REGION set the region; without them the AWS SDK's usual resolution, such as AWS_REGION, applies. --root needs a root you have run tofu init in.

Read-only SQL

sql and the run_query tool accept one SELECT or WITH statement. They reject before calling Athena:

  • Writes, DDL, and other statements: INSERT, UPDATE, DELETE, MERGE, CREATE, DROP, ALTER, UNLOAD, MSCK, EXPLAIN, SHOW, and the rest, wherever they appear outside a string or quoted identifier.
  • External functions (USING EXTERNAL FUNCTION), which would call a Lambda function.
  • More than one statement, comments, backtick identifiers, and unbalanced quotes or parentheses.

The statement keeps a final LIMIT up to the row cap; a larger one, LIMIT ALL, or none is replaced with the cap. Queries run in the semantic-events workgroup, whose result location and 10 GiB scan cutoff the client cannot override.

Query from an MCP client

bun run events:mcp starts an MCP server on standard input and output with the same capabilities as the script. It takes the same flags and environment variables and runs with the credentials of the process that starts it.

ToolWhat it does
describe_schemaThe columns, the table's location, and the query rules. Runs no query.
recent_eventsorganization_id, event_type, since, until, limit up to 1,000, and include_payload.
event_type_countsorganization_id, event_type, since, until, and limit up to 1,000.
run_querysql, one read-only statement, and max_rows up to 1,000, default 100.

Every tool is read-only. Results are JSON, and string cells longer than 2,000 characters are cut. Refused SQL, invalid arguments, and Athena failures return a tool error the model can read.

Register the server in any MCP client that launches local servers. Use absolute paths, because the client starts the server from its own working directory:

{
  "mcpServers": {
    "platform-events": {
      "command": "bun",
      "args": [
        "/path/to/deployments/packages/event-analytics-operator/src/mcp-server.ts",
        "--region",
        "us-east-2"
      ],
      "env": { "AWS_PROFILE": "platform-operator" }
    }
  }
}

In Claude Code:

claude mcp add --transport stdio --env AWS_PROFILE=platform-operator platform-events -- bun /path/to/deployments/packages/event-analytics-operator/src/mcp-server.ts --region us-east-2

Add --root /path/to/an/initialized/root to read the table's location from a root instead of using the defaults. Keep the server in your own, user-scoped client configuration; do not commit it to a project that tenants or their agents use.

On this page