Event Reference
Complete reference for all Semaphor observability event types, payloads, and error codes
This page documents every event type emitted by Semaphor's observability system. Events are delivered both as structured console logs and via webhook destinations. All field names use snake_case in the delivered payload.
Common Event Envelope
Every event shares these base fields:
| Field | Type | Description |
|---|---|---|
event_id | string | Unique identifier (UUID) |
event_type | string | Event type (e.g., query_failed) |
occurred_at | string (ISO 8601) | When the event occurred |
status | string | failed or aborted |
category | string | Event category: query, dashboard, token, or export |
component | string | Component that emitted the event |
message | string | Human-readable summary |
request_id | string | Correlation ID for the HTTP request |
Actor Context
These fields identify who triggered the action.
| Field | Type | Description |
|---|---|---|
actor_type | string | org_user or tenant_user |
actor_id | string | The user's ID (matches org_user_id or tenant_user_id) |
org_id | string | Organization ID |
project_id | string | Project ID |
tenant_id | string | Tenant ID (present for tenant users) |
org_user_id | string | Organization user ID |
tenant_user_id | string | Tenant user ID |
token_type | string | Token type used for authentication (e.g., dashboard, project) |
Not all actor fields appear on every event. For example, tenant_id and tenant_user_id are only present when the actor is a tenant user. Events triggered before authentication completes may have no actor context at all.
Resource Context
These fields identify the resource involved in the event.
| Field | Type | Description |
|---|---|---|
dashboard_id | string | Dashboard ID |
card_id | string | Card (visual) ID |
connection_id | string | Data connection ID |
Error Fields
Every event includes error details.
| Field | Type | Description |
|---|---|---|
error_code | string | Machine-readable error category (e.g., sql_error, auth_error) |
error_message | string | Human-readable error description |
error_details | string | Additional context, may be JSON-encoded |
Security Context
Events carry a normalized snapshot of the active security policies at the time of the failure. These fields are only present when the actor had security policies resolved.
| Field | Type | Description |
|---|---|---|
rls | array | Active row-level security policies |
sls | object | Active schema-level security policy |
cls | array | Active connection-level security policies |
Event Types
Semaphor emits four event types, each representing a distinct failure condition.
query_failed
Emitted when a SQL query fails during execution. This is typically the most frequent event type and covers syntax errors, connection issues, security policy failures, and more.
Additional fields:
| Field | Type | Description |
|---|---|---|
query_mode | string | sql (raw SQL) or config (visual builder) |
query_text | string | The SQL query that failed (truncated to 16 KB) |
query_text_truncated | boolean | true if the query was truncated |
card_type | string | Chart type (e.g., bar, line, table) |
connection_id | string | The data connection used |
Error codes:
| Code | Description |
|---|---|
sql_error | SQL syntax or execution error from the database |
auth_error | Authentication or authorization failure (HTTP 401) |
resource_not_found | Referenced resource does not exist |
rcls_error | Row-level security policy evaluation failed |
auto_join_error | Automatic table join could not be resolved |
comparison_error | Comparison query (e.g., period-over-period) failed |
kpi_error | KPI metric calculation failed |
decryption_error | Connection credentials could not be decrypted |
validation_error | Invalid request parameters (HTTP 400) |
internal_error | Unclassified server-side failure |
Example payload:
{
"event_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"event_type": "query_failed",
"occurred_at": "2025-06-15T14:32:08.123Z",
"status": "failed",
"category": "query",
"component": "query-api",
"message": "Query execution failed",
"request_id": "req_8f2a3b4c",
"org_id": "org_abc123",
"project_id": "prj_xyz789",
"dashboard_id": "d_dash001",
"card_id": "card_q1_revenue",
"connection_id": "conn_warehouse",
"actor_type": "tenant_user",
"actor_id": "tu_jane",
"org_user_id": null,
"tenant_user_id": "tu_jane",
"tenant_id": "tenant_acme",
"token_type": "dashboard",
"query_mode": "config",
"query_text": "SELECT date, SUM(revenue) FROM orders WHERE tenant_id = 'acme' GROUP BY date",
"card_type": "line",
"error_code": "sql_error",
"error_message": "column \"revenue\" does not exist",
"rls": [
{
"connection_id": "conn_warehouse",
"name": "tenant_filter",
"params": { "tenant_id": "acme" }
}
]
}dashboard_load_failed
Emitted when a dashboard template cannot be retrieved. Common causes include invalid dashboard IDs, expired tokens, or authorization failures.
Error codes:
| Code | Description |
|---|---|
auth_error | Authentication or authorization failure |
resource_not_found | Dashboard does not exist |
validation_error | Invalid request parameters |
internal_error | Unclassified server-side failure |
Example payload:
{
"event_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
"event_type": "dashboard_load_failed",
"occurred_at": "2025-06-15T14:33:12.456Z",
"status": "failed",
"category": "dashboard",
"component": "dashboard-api",
"message": "Dashboard load failed",
"request_id": "req_9c3d4e5f",
"org_id": "org_abc123",
"project_id": "prj_xyz789",
"dashboard_id": "d_invalid",
"actor_type": "tenant_user",
"actor_id": "tu_jane",
"tenant_user_id": "tu_jane",
"tenant_id": "tenant_acme",
"error_code": "resource_not_found",
"error_message": "Dashboard not found"
}token_generation_failed
Emitted when JWT embed token creation fails. Causes include an invalid dashboard secret, a missing tenant, or a security policy resolution error.
Additional fields:
| Field | Type | Description |
|---|---|---|
token_type | string | The token type requested (e.g., dashboard, project) |
Example payload:
{
"event_id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
"event_type": "token_generation_failed",
"occurred_at": "2025-06-15T14:34:05.789Z",
"status": "failed",
"category": "token",
"component": "token-api",
"message": "Token generation failed",
"request_id": "req_0d4e5f6a",
"org_id": "org_abc123",
"project_id": "prj_xyz789",
"dashboard_id": "d_dash001",
"token_type": "dashboard",
"org_user_id": "ou_admin01",
"error_code": "auth_error",
"error_message": "Invalid dashboard secret",
"rls": [
{
"name": "tenant_filter",
"params": { "tenant_id": "acme" }
}
]
}export_failed
Emitted when a CSV or PDF export fails. Exports can fail at two stages: creation (validating the request) and execution (generating the file).
Additional fields:
| Field | Type | Description |
|---|---|---|
operation | string | export_create or export_execute |
card_type | string | Chart type of the exported card |
card_title | string | Display title of the exported card |
Example payload:
{
"event_id": "c9d0e1f2-a3b4-5678-cdef-789012345678",
"event_type": "export_failed",
"occurred_at": "2025-06-15T14:40:15.567Z",
"status": "failed",
"category": "export",
"component": "exports-api",
"message": "Export failed",
"request_id": "req_6d0e1f2a",
"org_id": "org_abc123",
"project_id": "prj_xyz789",
"dashboard_id": "d_dash001",
"connection_id": "conn_warehouse",
"actor_type": "tenant_user",
"actor_id": "tu_jane",
"tenant_user_id": "tu_jane",
"tenant_id": "tenant_acme",
"operation": "export_create",
"card_type": "table",
"card_title": "Q1 Revenue by Region",
"error_code": "validation_error",
"error_message": "Export would require 1,500,000 rows, exceeding the 1,000,000 row limit"
}Data Privacy
What is never included
Observability events are designed to aid debugging without exposing sensitive data. The following are never included in event payloads:
- Raw JWT tokens
- Database connection strings or passwords
- Full security policy definitions (only normalized references are included)
Query text is truncated at 16 KB. If truncation occurs, query_text_truncated is set to true.
Structured Log Format
For self-hosted deployments, every event is written to the console as a single-line JSON object. The log output includes two additional fields beyond the webhook payload:
| Field | Type | Description |
|---|---|---|
timestamp | string (ISO 8601) | Same value as occurred_at |
level | string | warn for aborted events, error for all others |
These logs appear in your Docker container output and can be collected by any log aggregation tool (Datadog, Grafana Loki, CloudWatch, etc.).
{"timestamp":"2025-06-15T14:32:08.123Z","level":"error","component":"query-api","category":"query","event":"query_failed","message":"Query execution failed","event_id":"a1b2c3d4-e5f6-7890-abcd-ef1234567890","request_id":"req_8f2a3b4c","org_id":"org_abc123","error_code":"sql_error","error_message":"column \"revenue\" does not exist"}