> ## Documentation Index
> Fetch the complete documentation index at: https://docs.firebolt.io/llms.txt
> Use this file to discover all available pages before exploring further.

> Configure structured engine logs for OpenTelemetry, Google Cloud, Amazon CloudWatch, and Azure Monitor.

# Structured logging

A Firebolt Engine writes one log record per line. Set `logging.format` in the Engine YAML
configuration to select the field names and structure expected by your log collector:

```yaml theme={"theme":{"light":"css-variables","dark":"css-variables"}}
schema_version: "1.0"

logging:
  level: info
  format: google_cloud
  sinks:
    - type: stderr
```

The format applies to every configured sink. Log records can include a query ID, request ID, query
label, component, thread information, source location, region, Instance ID, and active trace context
when those values are available.

## Formats

| Value | Output |
| :- | :- |
| `text` | Human-readable text. |
| `json` | The Firebolt JSON format. This is the default. |
| `otel` | JSON aligned with the OpenTelemetry Log Data Model and semantic conventions. It is not an OTLP wire payload. |
| `google_cloud` | JSON using the special fields recognized by Google Cloud Structured Logging. |
| `aws_cloudwatch` | Flat JSON for CloudWatch Logs field discovery, using OpenTelemetry severity and trace field names. |
| `azure_monitor` | JSON for Azure Monitor container log collection, including the top-level `level` field used to populate `ContainerLogV2.LogLevel`. |

Changing the format changes field names and nesting. Update queries, parsing rules, and alert rules
that read the previous format before changing `logging.format`.

### Firebolt JSON

The `json` format uses Firebolt's own schema:

```json theme={"theme":{"light":"css-variables","dark":"css-variables"}}
{"ts":"2026-09-11T10:15:30.123456Z","thread_name":"Query","thread_id":"123","lvl":"info","query_label":"<NOT SET>","request_id":"request-1","query_id":"query-1","component":"HTTPHandler","msg":"Query started","source_file":"src/Server/HTTPHandler.cpp","source_line":"900"}
```

Empty values remain present in this format. `thread_id` and `source_line` are JSON strings.

### OpenTelemetry

The `otel` format projects each record onto the OpenTelemetry Log Data Model. It uses `timestamp`,
`severityText`, `severityNumber`, `body`, `traceId`, `spanId`, `traceFlags`, `resource`, `scope`, and
`attributes`. Attribute names follow OpenTelemetry semantic conventions where a convention exists,
including `thread.id`, `thread.name`, `code.file.path`, `code.line.number`, `cloud.region`, and
`service.instance.id`. Firebolt correlation fields use the `firebolt.*` namespace.

This format is JSON Lines for a console or file collector. Send logs to an OTLP endpoint through an
OpenTelemetry Collector or another OTLP exporter; an OTLP endpoint expects a batched OTLP envelope,
not individual JSON log records.

### Google Cloud

The `google_cloud` format uses `time`, `severity`, and `message`. It writes source and trace context
to these Google Cloud fields when available:

* `logging.googleapis.com/sourceLocation`
* `logging.googleapis.com/trace`
* `logging.googleapis.com/spanId`
* `logging.googleapis.com/trace_sampled`

Google Cloud moves these fields into the corresponding `LogEntry` fields during ingestion. Other
Firebolt fields remain in the JSON payload. See [Structured logging](https://cloud.google.com/logging/docs/structured-logging)
in the Google Cloud documentation.

### Amazon CloudWatch

The `aws_cloudwatch` format is flat JSON so CloudWatch Logs Insights can discover every field. It
uses `severityText`, `severityNumber`, `traceId`, and `spanId`, which also match OpenTelemetry field
names. CloudWatch assigns the log event timestamp during transport; the JSON `timestamp` field is
available for queries but does not replace CloudWatch's generated `@timestamp` field.

See [Supported logs and discovered fields](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/CWL_AnalyzeLogData-discoverable-fields.html)
in the CloudWatch Logs documentation.

### Azure Monitor

The `azure_monitor` format writes flat JSON with `timestamp`, `level`, and `message`. Azure Monitor
Container Insights uses a top-level `level` value from a valid JSON log message to populate the
`LogLevel` column in `ContainerLogV2`. Other fields remain in the dynamic `LogMessage` value.

See [Configure the ContainerLogV2 schema](https://learn.microsoft.com/azure/azure-monitor/containers/container-insights-logs-schema)
in the Azure Monitor documentation.

## Trace correlation

The structured formats emit trace fields only when a valid OpenTelemetry span is active on
the logging thread. Enabling a structured format does not enable tracing. Configure OpenTelemetry
tracing separately with the `otel` configuration block.