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`, `assistant`, 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 nine event types, each representing a distinct failure or abort 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" }
    }
  ]
}

`assistant_request_failed`

Emitted when an AI assistant request fails during processing. This covers authentication errors, invalid payloads, and unexpected runtime failures.

Additional fields:

Field	Type	Description
`assistant_id`	string	Assistant identifier
`assistant_profile_id`	string	Assistant profile ID
`assistant_request_id`	string	Request ID within the assistant session
`conversation_id`	string	Conversation thread ID
`provider`	string	LLM provider (e.g., `openai`)
`model_name`	string	Model used (e.g., `gpt-4o`)

Example payload:

{
  "event_id": "d4e5f6a7-b8c9-0123-defa-234567890123",
  "event_type": "assistant_request_failed",
  "occurred_at": "2025-06-15T14:35:22.012Z",
  "status": "failed",
  "category": "assistant",
  "component": "assistant-api",
  "message": "Assistant request failed",
  "request_id": "req_1e5f6a7b",
  "org_id": "org_abc123",
  "project_id": "prj_xyz789",
  "actor_type": "org_user",
  "actor_id": "ou_admin01",
  "org_user_id": "ou_admin01",
  "assistant_id": "asst_data01",
  "assistant_profile_id": "ap_default",
  "assistant_request_id": "areq_f8c2",
  "conversation_id": "conv_91ab",
  "provider": "openai",
  "model_name": "gpt-4o",
  "error_code": "assistant_request_failed",
  "error_message": "Context window exceeded"
}

`assistant_request_aborted`

Emitted when an assistant request is cancelled by the user or terminated due to a timeout.

This event has a status of aborted and is logged at warn level instead of error.

Uses the same additional fields as assistant_request_failed.

Example payload:

{
  "event_id": "e5f6a7b8-c9d0-1234-efab-345678901234",
  "event_type": "assistant_request_aborted",
  "occurred_at": "2025-06-15T14:36:45.345Z",
  "status": "aborted",
  "category": "assistant",
  "component": "assistant-api",
  "message": "Assistant request aborted",
  "request_id": "req_2f6a7b8c",
  "org_id": "org_abc123",
  "project_id": "prj_xyz789",
  "actor_type": "org_user",
  "actor_id": "ou_admin01",
  "org_user_id": "ou_admin01",
  "assistant_id": "asst_data01",
  "assistant_profile_id": "ap_default",
  "assistant_request_id": "areq_d4e1",
  "conversation_id": "conv_91ab",
  "provider": "openai",
  "model_name": "gpt-4o",
  "error_code": null,
  "error_message": null
}

`assistant_tool_failed`

Emitted when a tool call within an assistant conversation fails. A tool call is an action the assistant takes on behalf of the user, such as executing a query or generating a chart.

Additional fields:

All fields from assistant_request_failed, plus:

Field	Type	Description
`tool_name`	string	Name of the tool that failed

Example payload:

{
  "event_id": "f6a7b8c9-d0e1-2345-fabc-456789012345",
  "event_type": "assistant_tool_failed",
  "occurred_at": "2025-06-15T14:37:18.678Z",
  "status": "failed",
  "category": "assistant",
  "component": "assistant-api",
  "message": "Assistant tool failed",
  "request_id": "req_3a7b8c9d",
  "org_id": "org_abc123",
  "project_id": "prj_xyz789",
  "actor_type": "org_user",
  "actor_id": "ou_admin01",
  "org_user_id": "ou_admin01",
  "assistant_id": "asst_data01",
  "assistant_profile_id": "ap_default",
  "assistant_request_id": "areq_c3d0",
  "conversation_id": "conv_91ab",
  "provider": "openai",
  "model_name": "gpt-4o",
  "tool_name": "executeQuery",
  "error_code": "tool_execution_failed",
  "error_message": "Query timed out after 30 seconds"
}

`assistant_provider_error`

Emitted when the LLM provider returns an error or is unreachable. This includes rate limits, service outages, and network timeouts.

Uses the same additional fields as assistant_request_failed.

Example payload:

{
  "event_id": "a7b8c9d0-e1f2-3456-abcd-567890123456",
  "event_type": "assistant_provider_error",
  "occurred_at": "2025-06-15T14:38:05.901Z",
  "status": "failed",
  "category": "assistant",
  "component": "assistant-api",
  "message": "Assistant provider error",
  "request_id": "req_4b8c9d0e",
  "org_id": "org_abc123",
  "project_id": "prj_xyz789",
  "actor_type": "org_user",
  "actor_id": "ou_admin01",
  "org_user_id": "ou_admin01",
  "assistant_id": "asst_data01",
  "assistant_profile_id": "ap_default",
  "assistant_request_id": "areq_b2c9",
  "conversation_id": "conv_91ab",
  "provider": "openai",
  "model_name": "gpt-4o",
  "error_code": "provider_error",
  "error_message": "OpenAI API returned 429: Rate limit exceeded"
}

`assistant_dynamic_visual_failed`

Emitted when dynamic chart generation falls back or fails entirely. Dynamic visuals are AI-generated chart configurations that render custom visualizations.

Additional fields:

All fields from assistant_request_failed, plus:

Field	Type	Description
`tool_name`	string	The dynamic visual tool that failed (e.g., `generateDynamicVisual`)

Example payload:

{
  "event_id": "b8c9d0e1-f2a3-4567-bcde-678901234567",
  "event_type": "assistant_dynamic_visual_failed",
  "occurred_at": "2025-06-15T14:39:30.234Z",
  "status": "failed",
  "category": "assistant",
  "component": "assistant-api",
  "message": "Assistant dynamic visual generation failed",
  "request_id": "req_5c9d0e1f",
  "org_id": "org_abc123",
  "project_id": "prj_xyz789",
  "actor_type": "org_user",
  "actor_id": "ou_admin01",
  "org_user_id": "ou_admin01",
  "assistant_id": "asst_data01",
  "assistant_profile_id": "ap_default",
  "assistant_request_id": "areq_a1b8",
  "conversation_id": "conv_91ab",
  "provider": "openai",
  "model_name": "gpt-4o",
  "tool_name": "generateDynamicVisual",
  "error_code": "dynamic_visual_fallback",
  "error_message": "Dynamic visual generation fell back (invalid chart configuration)"
}

`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
AI conversation transcripts or chain-of-thought reasoning
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.).

Example console log line

{"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"}

Event Reference

On this page