# Logfire (/integrations/logfire)





{/* MANUAL-CONTENT-START:intro */}

Use [Pydantic Logfire](https://pydantic.dev/logfire) to query telemetry collected with OpenTelemetry. Search spans and logs by message, service, span name, severity, environment, or exception status, or run PostgreSQL-compatible read-only SQL over the `records` and `metrics` tables.

Trace lookup returns spans ordered by time with parent-child relationships for request investigation. Credential lookup identifies the organization and project targeted by a read token.

Create a project **read token** under **Settings → Read tokens**. Sim detects the cloud region from its prefix. For a self-hosted instance, set **Host** to a publicly resolvable HTTPS base URL that Sim can reach.

{/* MANUAL-CONTENT-END */}

## Use the block [#usage-instructions]

Run SQL over your observability data, search spans and logs with structured filters, pull an entire trace by ID, and confirm which project a read token targets.

## Actions [#actions]

### Logfire Query [#logfire-query]

Run a read-only SQL query against Logfire traces, logs, and metrics. Reads the records and metrics tables using PostgreSQL-compatible syntax.

#### Input [#input]

| Parameter | Type | Required | Description |
| - | - | - | - |
| `apiKey` | string | Yes | Logfire read token |
| `region` | string | No | Logfire data region: auto, us, or eu. Auto reads the region from the token. |
| `host` | string | No | Base URL of a self-hosted Logfire instance, e.g. [https://logfire.example.com](https://logfire.example.com). Overrides region. Leave blank for Logfire Cloud. |
| `sql` | string | Yes | SQL SELECT query to run against the records or metrics table |
| `minTimestamp` | string | No | ISO 8601 lower bound on start\_timestamp. Defaults to 2020-01-01T00:00:00Z when omitted. |
| `maxTimestamp` | string | No | ISO 8601 upper bound on start\_timestamp |
| `limit` | number | No | Maximum rows to return. Logfire defaults to 100 and caps at 10000. |
| `timezone` | string | No | IANA timezone used to evaluate the query, for example Europe/Paris |
| `environment` | string | No | Restrict results to a single deployment environment |

#### Output [#output]

| Parameter | Type | Description |
| - | - | - |
| `rows` | array | Result rows. Row fields depend on the query projection. |
| `columns` | array | Column metadata for the result set |
| ↳ `name` | string | Column name |
| ↳ `datatype` | json | Arrow datatype of the column |
| ↳ `nullable` | boolean | Whether the column is nullable |
| `rowCount` | number | Number of rows returned |

### Logfire Search Records [#logfire-search-records]

Search Logfire spans and logs using structured filters for message text, service, span name, severity, environment, and exceptions. Returns the most recent matches first without writing SQL.

<ReferenceDetails>
  #### Input [#input-1]

  | Parameter | Type | Required | Description |
  | - | - | - | - |
  | `apiKey` | string | Yes | Logfire read token |
  | `region` | string | No | Logfire data region: auto, us, or eu. Auto reads the region from the token. |
  | `host` | string | No | Base URL of a self-hosted Logfire instance, e.g. [https://logfire.example.com](https://logfire.example.com). Overrides region. Leave blank for Logfire Cloud. |
  | `query` | string | No | Case-insensitive text to match within the record message |
  | `service` | string | No | Exact service name to filter on |
  | `spanName` | string | No | Exact span name to filter on |
  | `minLevel` | string | No | Minimum severity to include: trace, debug, info, notice, warn, error, or fatal |
  | `exceptionsOnly` | boolean | No | Only return records that recorded an exception |
  | `environment` | string | No | Restrict results to a single deployment environment |
  | `minTimestamp` | string | No | ISO 8601 lower bound on start\_timestamp. Defaults to 2020-01-01T00:00:00Z when omitted. |
  | `maxTimestamp` | string | No | ISO 8601 upper bound on start\_timestamp |
  | `limit` | number | No | Maximum records to return. Logfire defaults to 100 and caps at 10000. |

  #### Output [#output-1]

  | Parameter | Type | Description |
  | - | - | - |
  | `rows` | array | Matching spans and logs, most recent first |
  | ↳ `startTimestamp` | string | UTC time the span started |
  | ↳ `endTimestamp` | string | UTC time the span ended |
  | ↳ `duration` | number | Span duration in seconds. Null for logs. |
  | ↳ `level` | string | Severity name, such as info, warn, or error |
  | ↳ `message` | string | Human-readable message |
  | ↳ `spanName` | string | Template label for similar records |
  | ↳ `kind` | string | Record kind: span, log, span\_event, or pending\_span |
  | ↳ `serviceName` | string | Service that emitted the record |
  | ↳ `deploymentEnvironment` | string | Deployment environment of the record |
  | ↳ `traceId` | string | Trace this record belongs to |
  | ↳ `spanId` | string | Identifier of this span |
  | ↳ `parentSpanId` | string | Parent span identifier |
  | ↳ `isException` | boolean | Whether an exception was recorded on the span |
  | ↳ `exceptionType` | string | Fully qualified exception class name |
  | ↳ `exceptionMessage` | string | Exception message |
  | `rowCount` | number | Number of rows returned |
  | `sql` | string | SQL query that was executed against Logfire |
</ReferenceDetails>

### Logfire Get Trace [#logfire-get-trace]

Fetch every span and log belonging to a Logfire trace, ordered from earliest to latest, so a single request can be reconstructed end to end.

<ReferenceDetails>
  #### Input [#input-2]

  | Parameter | Type | Required | Description |
  | - | - | - | - |
  | `apiKey` | string | Yes | Logfire read token |
  | `region` | string | No | Logfire data region: auto, us, or eu. Auto reads the region from the token. |
  | `host` | string | No | Base URL of a self-hosted Logfire instance, e.g. [https://logfire.example.com](https://logfire.example.com). Overrides region. Leave blank for Logfire Cloud. |
  | `traceId` | string | Yes | 32-character hexadecimal trace identifier |
  | `minTimestamp` | string | No | ISO 8601 lower bound on start\_timestamp. Defaults to 2020-01-01T00:00:00Z when omitted. |
  | `maxTimestamp` | string | No | ISO 8601 upper bound on start\_timestamp |
  | `limit` | number | No | Maximum spans to return. Logfire defaults to 100 and caps at 10000. |

  #### Output [#output-2]

  | Parameter | Type | Description |
  | - | - | - |
  | `rows` | array | Spans and logs in the trace, earliest first |
  | ↳ `startTimestamp` | string | UTC time the span started |
  | ↳ `endTimestamp` | string | UTC time the span ended |
  | ↳ `duration` | number | Span duration in seconds. Null for logs. |
  | ↳ `level` | string | Severity name, such as info, warn, or error |
  | ↳ `message` | string | Human-readable message |
  | ↳ `spanName` | string | Template label for similar records |
  | ↳ `kind` | string | Record kind: span, log, span\_event, or pending\_span |
  | ↳ `serviceName` | string | Service that emitted the record |
  | ↳ `deploymentEnvironment` | string | Deployment environment of the record |
  | ↳ `traceId` | string | Trace this record belongs to |
  | ↳ `spanId` | string | Identifier of this span |
  | ↳ `parentSpanId` | string | Parent span identifier |
  | ↳ `isException` | boolean | Whether an exception was recorded on the span |
  | ↳ `exceptionType` | string | Fully qualified exception class name |
  | ↳ `exceptionMessage` | string | Exception message |
  | `rowCount` | number | Number of rows returned |
  | `sql` | string | SQL query that was executed against Logfire |
</ReferenceDetails>

### Logfire Get Token Info [#logfire-get-token-info]

Resolve which Logfire organization and project a read token belongs to. Useful for confirming a credential targets the expected project before querying it.

#### Input [#input-3]

| Parameter | Type | Required | Description |
| - | - | - | - |
| `apiKey` | string | Yes | Logfire read token |
| `region` | string | No | Logfire data region: auto, us, or eu. Auto reads the region from the token. |
| `host` | string | No | Base URL of a self-hosted Logfire instance, e.g. [https://logfire.example.com](https://logfire.example.com). Overrides region. Leave blank for Logfire Cloud. |

#### Output [#output-3]

| Parameter | Type | Description |
| - | - | - |
| `organizationName` | string | Logfire organization the read token belongs to |
| `projectName` | string | Logfire project the read token belongs to |
| `expiresAt` | string | When the read token expires. Null when it never expires. |
| `spendingCapReachedAt` | string | When the organization's spending cap was reached, which stops queries. Null when it has not been reached. |