---
title: "overlane observe trace"
description: "Show one run's events, logs and spans together"
---

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

# overlane observe trace

{/* Generated by apps/docs/scripts/generate.mjs (CLI pages from the command registry in packages/cli). Do not edit; run `pnpm --filter @overlane/docs gen`. */}

Everything recorded for a run, stitched by run ID: its ordered event stream, its log lines and its spans, with the run's status, cost and tokens.

## Usage

```sh
overlane observe trace --run RUN
```

## Flags

| Flag | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `--run` | string | yes |  | The run ID |

## Examples

```sh
overlane observe trace --run run-12
overlane observe trace --run run-12 --json
```

## Behavior

- Effect: `read` (changes nothing).
- Needs credentials: yes. Uses the network: yes.
- Supports `--dry-run`: no. Accepts `--force`: no.
- Machine-readable description: `overlane schema observe trace`.

## Result

With `--json` (the default when stdout is not a terminal) the command prints this JSON Schema's shape on stdout.

```json
{
  "type": "object",
  "properties": {
    "tenantId": {
      "type": "string",
      "minLength": 1,
      "maxLength": 128,
      "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:-]*$",
      "description": "tenant identifier"
    },
    "projectId": {
      "type": "string",
      "minLength": 1,
      "maxLength": 128,
      "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:-]*$",
      "description": "project identifier"
    },
    "runId": {
      "type": "string",
      "minLength": 1,
      "maxLength": 128
    },
    "run": {
      "anyOf": [
        {
          "type": "object",
          "properties": {
            "tenantId": {
              "type": "string",
              "minLength": 1,
              "maxLength": 128,
              "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:-]*$",
              "description": "tenant identifier"
            },
            "projectId": {
              "type": "string",
              "minLength": 1,
              "maxLength": 128,
              "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:-]*$",
              "description": "project identifier"
            },
            "runId": {
              "type": "string",
              "minLength": 1,
              "maxLength": 128
            },
            "agent": {
              "type": "string",
              "minLength": 1,
              "maxLength": 128
            },
            "status": {
              "type": "string",
              "enum": [
                "running",
                "passed",
                "failed",
                "paused"
              ]
            },
            "taskId": {
              "type": "string",
              "minLength": 1,
              "maxLength": 128
            },
            "pr": {
              "type": "string",
              "minLength": 1,
              "maxLength": 128
            },
            "startedAt": {
              "type": "string",
              "format": "date-time",
              "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"
            },
            "endedAt": {
              "type": "string",
              "format": "date-time",
              "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"
            },
            "lastEventAt": {
              "type": "string",
              "format": "date-time",
              "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"
            },
            "costMicros": {
              "type": "integer",
              "minimum": 0,
              "maximum": 9007199254740991
            },
            "tokens": {
              "type": "integer",
              "minimum": 0,
              "maximum": 9007199254740991
            },
            "reviewOutcome": {
              "type": "string",
              "enum": [
                "approved",
                "changes_requested",
                "pending",
                "none"
              ]
            }
          },
          "required": [
            "tenantId",
            "projectId",
            "runId",
            "agent",
            "status",
            "startedAt",
            "lastEventAt",
            "costMicros",
            "tokens",
            "reviewOutcome"
          ],
          "additionalProperties": false
        },
        {
          "type": "null"
        }
      ]
    },
    "events": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "schemaVersion": {
            "type": "string",
            "const": "1"
          },
          "tenantId": {
            "type": "string",
            "minLength": 1,
            "maxLength": 128,
            "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:-]*$",
            "description": "tenant identifier"
          },
          "projectId": {
            "type": "string",
            "minLength": 1,
            "maxLength": 128,
            "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:-]*$",
            "description": "project identifier"
          },
          "runId": {
            "type": "string",
            "minLength": 1,
            "maxLength": 128
          },
          "eventId": {
            "type": "string",
            "minLength": 8,
            "maxLength": 128
          },
          "type": {
            "type": "string",
            "enum": [
              "run.started",
              "run.tool.started",
              "run.tool.finished",
              "run.file.edited",
              "run.commit",
              "run.log",
              "run.cost",
              "run.decision",
              "run.ended"
            ]
          },
          "agent": {
            "type": "string",
            "minLength": 1,
            "maxLength": 128
          },
          "status": {
            "type": "string",
            "enum": [
              "running",
              "passed",
              "failed",
              "paused"
            ]
          },
          "occurredAt": {
            "type": "string",
            "format": "date-time",
            "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"
          },
          "label": {
            "type": "string",
            "maxLength": 300
          },
          "detail": {
            "type": "string",
            "maxLength": 1000
          },
          "level": {
            "type": "string",
            "enum": [
              "info",
              "warn",
              "error"
            ]
          },
          "costMicros": {
            "type": "integer",
            "minimum": 0,
            "maximum": 9007199254740991
          },
          "tokens": {
            "type": "integer",
            "minimum": 0,
            "maximum": 9007199254740991
          },
          "taskId": {
            "type": "string",
            "minLength": 1,
            "maxLength": 128
          },
          "pr": {
            "type": "string",
            "minLength": 1,
            "maxLength": 128
          },
          "reviewOutcome": {
            "type": "string",
            "enum": [
              "approved",
              "changes_requested",
              "pending",
              "none"
            ]
          },
          "toolCall": {
            "type": "object",
            "properties": {
              "toolCallId": {
                "type": "string",
                "minLength": 1,
                "maxLength": 128
              },
              "name": {
                "type": "string",
                "minLength": 1,
                "maxLength": 128
              },
              "input": {
                "type": "string",
                "maxLength": 2000
              },
              "status": {
                "type": "string",
                "enum": [
                  "ok",
                  "error",
                  "refused"
                ]
              },
              "durationMs": {
                "type": "integer",
                "minimum": 0,
                "maximum": 9007199254740991
              },
              "output": {
                "type": "string",
                "maxLength": 4000
              },
              "unavailable": {
                "maxItems": 3,
                "type": "array",
                "items": {
                  "type": "string",
                  "enum": [
                    "durationMs",
                    "output",
                    "status"
                  ]
                }
              }
            },
            "required": [
              "toolCallId",
              "name",
              "input"
            ],
            "additionalProperties": false
          },
          "fileEdit": {
            "type": "object",
            "properties": {
              "toolCallId": {
                "type": "string",
                "minLength": 1,
                "maxLength": 128
              },
              "diff": {
                "type": "object",
                "properties": {
                  "path": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 1000
                  },
                  "previousPath": {
                    "anyOf": [
                      {
                        "type": "string",
                        "minLength": 1,
                        "maxLength": 1000
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "status": {
                    "type": "string",
                    "enum": [
                      "added",
                      "modified",
                      "deleted",
                      "renamed",
                      "binary"
                    ]
                  },
                  "additions": {
                    "type": "integer",
                    "minimum": 0,
                    "maximum": 9007199254740991
                  },
                  "deletions": {
                    "type": "integer",
                    "minimum": 0,
                    "maximum": 9007199254740991
                  },
                  "truncated": {
                    "type": "boolean"
                  },
                  "hunks": {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "properties": {
                        "oldStart": {
                          "type": "integer",
                          "minimum": 0,
                          "maximum": 9007199254740991
                        },
                        "oldLines": {
                          "type": "integer",
                          "minimum": 0,
                          "maximum": 9007199254740991
                        },
                        "newStart": {
                          "type": "integer",
                          "minimum": 0,
                          "maximum": 9007199254740991
                        },
                        "newLines": {
                          "type": "integer",
                          "minimum": 0,
                          "maximum": 9007199254740991
                        },
                        "lines": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "type": {
                                "type": "string",
                                "enum": [
                                  "context",
                                  "add",
                                  "delete"
                                ]
                              },
                              "oldLine": {
                                "anyOf": [
                                  {
                                    "type": "integer",
                                    "exclusiveMinimum": 0,
                                    "maximum": 9007199254740991
                                  },
                                  {
                                    "type": "null"
                                  }
                                ]
                              },
                              "newLine": {
                                "anyOf": [
                                  {
                                    "type": "integer",
                                    "exclusiveMinimum": 0,
                                    "maximum": 9007199254740991
                                  },
                                  {
                                    "type": "null"
                                  }
                                ]
                              },
                              "text": {
                                "type": "string"
                              },
                              "noNewline": {
                                "type": "boolean"
                              }
                            },
                            "required": [
                              "type",
                              "oldLine",
                              "newLine",
                              "text"
                            ],
                            "additionalProperties": false
                          }
                        }
                      },
                      "required": [
                        "oldStart",
                        "oldLines",
                        "newStart",
                        "newLines",
                        "lines"
                      ],
                      "additionalProperties": false
                    }
                  }
                },
                "required": [
                  "path",
                  "previousPath",
                  "status",
                  "additions",
                  "deletions",
                  "truncated",
                  "hunks"
                ],
                "additionalProperties": false
              }
            },
            "required": [
              "diff"
            ],
            "additionalProperties": false
          },
          "commit": {
            "type": "object",
            "properties": {
              "sha": {
                "type": "string",
                "pattern": "^[0-9a-f]{40}$|^[0-9a-f]{64}$"
              },
              "branch": {
                "type": "string",
                "minLength": 1,
                "maxLength": 255
              },
              "message": {
                "type": "string",
                "maxLength": 300
              },
              "filesChanged": {
                "type": "integer",
                "minimum": 0,
                "maximum": 9007199254740991
              },
              "additions": {
                "type": "integer",
                "minimum": 0,
                "maximum": 9007199254740991
              },
              "deletions": {
                "type": "integer",
                "minimum": 0,
                "maximum": 9007199254740991
              }
            },
            "required": [
              "sha",
              "message",
              "filesChanged",
              "additions",
              "deletions"
            ],
            "additionalProperties": false
          },
          "redacted": {
            "type": "boolean"
          },
          "redactions": {
            "type": "integer",
            "minimum": 0,
            "maximum": 9007199254740991
          },
          "sequence": {
            "type": "integer",
            "exclusiveMinimum": 0,
            "maximum": 9007199254740991
          }
        },
        "required": [
          "schemaVersion",
          "tenantId",
          "projectId",
          "runId",
          "eventId",
          "type",
          "agent",
          "status",
          "occurredAt",
          "sequence"
        ],
        "additionalProperties": false
      }
    },
    "logs": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "schemaVersion": {
            "type": "string",
            "const": "1"
          },
          "tenantId": {
            "type": "string",
            "minLength": 1,
            "maxLength": 128,
            "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:-]*$",
            "description": "tenant identifier"
          },
          "projectId": {
            "type": "string",
            "minLength": 1,
            "maxLength": 128,
            "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:-]*$",
            "description": "project identifier"
          },
          "runId": {
            "type": "string",
            "minLength": 1,
            "maxLength": 128
          },
          "logId": {
            "type": "string",
            "minLength": 8,
            "maxLength": 128
          },
          "at": {
            "type": "string",
            "format": "date-time",
            "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"
          },
          "level": {
            "type": "string",
            "enum": [
              "info",
              "warn",
              "error"
            ]
          },
          "source": {
            "type": "string",
            "minLength": 1,
            "maxLength": 60
          },
          "agent": {
            "type": "string",
            "minLength": 1,
            "maxLength": 128
          },
          "message": {
            "type": "string",
            "maxLength": 4000
          },
          "redacted": {
            "type": "boolean"
          },
          "redactions": {
            "type": "integer",
            "minimum": 0,
            "maximum": 9007199254740991
          }
        },
        "required": [
          "schemaVersion",
          "tenantId",
          "projectId",
          "runId",
          "logId",
          "at",
          "level",
          "source",
          "message",
          "redacted",
          "redactions"
        ],
        "additionalProperties": false
      }
    },
    "spans": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "schemaVersion": {
            "type": "string",
            "const": "1"
          },
          "tenantId": {
            "type": "string",
            "minLength": 1,
            "maxLength": 128,
            "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:-]*$",
            "description": "tenant identifier"
          },
          "projectId": {
            "type": "string",
            "minLength": 1,
            "maxLength": 128,
            "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:-]*$",
            "description": "project identifier"
          },
          "runId": {
            "type": "string",
            "minLength": 1,
            "maxLength": 128
          },
          "spanId": {
            "type": "string",
            "minLength": 4,
            "maxLength": 128
          },
          "parentSpanId": {
            "type": "string",
            "minLength": 4,
            "maxLength": 128
          },
          "name": {
            "type": "string",
            "minLength": 1,
            "maxLength": 200
          },
          "agent": {
            "type": "string",
            "minLength": 1,
            "maxLength": 128
          },
          "tool": {
            "type": "string",
            "minLength": 1,
            "maxLength": 128
          },
          "startedAt": {
            "type": "string",
            "format": "date-time",
            "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"
          },
          "durationMs": {
            "type": "integer",
            "minimum": 0,
            "maximum": 9007199254740991
          },
          "status": {
            "type": "string",
            "enum": [
              "ok",
              "error"
            ]
          },
          "attributes": {
            "type": "object",
            "propertyNames": {
              "type": "string",
              "maxLength": 60
            },
            "additionalProperties": {
              "type": "string",
              "maxLength": 500
            }
          },
          "redactions": {
            "type": "integer",
            "minimum": 0,
            "maximum": 9007199254740991
          }
        },
        "required": [
          "schemaVersion",
          "tenantId",
          "projectId",
          "runId",
          "spanId",
          "name",
          "agent",
          "startedAt",
          "durationMs",
          "status",
          "attributes",
          "redactions"
        ],
        "additionalProperties": false
      }
    }
  },
  "required": [
    "tenantId",
    "projectId",
    "runId",
    "run",
    "events",
    "logs",
    "spans"
  ],
  "additionalProperties": false
}
```

See [exit codes](/cli/#exit-codes) for the status the process returns.

Source: https://docs.overlane.app/cli/observe-trace/index.mdx