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

# Jaeger

> Virtualize a Jaeger query service from Node.

`JaegerVFS` mounts an existing Jaeger query service as read-only JSON files:
each service becomes a folder with its operations and one file per trace. Set up the connection as in [Jaeger setup](https://docs.mirage.strukto.ai/home/setup/jaeger.md).

## Install

```bash theme={null}
npm install @struktoai/mirage-node
```

## Configure

```ts theme={null}
import { JaegerVFS, MountMode, Workspace } from '@struktoai/mirage-node'

const jaeger = new JaegerVFS({ host: 'http://localhost:16686' })
const ws = new Workspace({ '/jaeger': jaeger }, { mode: MountMode.READ })

const result = await ws.shell("jq -r '.[].name' /jaeger/services/frontend/operations.json")
console.log(result.stdoutText)
await ws.close()
```

`host` is the query service's base URL; it needs no credentials.
`defaultTraceLimit`, `defaultFromTimestamp` and `defaultToTimestamp` bound
each trace listing. The class ships in `@struktoai/mirage-node` only. In a
YAML config or `buildVfs('jaeger', ...)`, the same fields are snake\_case
(`default_trace_limit`).

### Fields

**host** `string` (default: '[http://localhost:16686](http://localhost:16686)')

Jaeger query service URL.

**defaultTraceLimit** `number` (default: 100)

The most traces one service's `traces/` listing shows, newest first. An older trace is still readable by its id.

**defaultFromTimestamp** `string`

Lower bound of trace listings, an ISO 8601 timestamp. Unset searches from the beginning.

**defaultToTimestamp** `string`

Upper bound of trace listings, an ISO 8601 timestamp. Unset means now.

**timeout** `number` (default: DEFAULT\_TIMEOUT)

Seconds a request may wait to connect, or between two reads of its answer, before it fails; a download that keeps flowing is never cut off.

## Layout

```text theme={null}
/jaeger/
  services/
    <service>/
      operations.json
      traces/
        <trace-id>.json
```

* **`services/`:** one folder per service Jaeger reports, including Jaeger's
  own `jaeger` service when it traces itself.
* **`operations.json`:** the service's operation records, as Jaeger returns
  them.
* **`traces/<trace-id>.json`:** the trace document Jaeger returns, with
  `traceID`, `spans`, `processes` and `warnings`.

## Behavior

* **Read only:** the mount has no write operations.
* **Trace listing:** `traces/` shows the newest `defaultTraceLimit` traces
  (100) of the service between `defaultFromTimestamp` and
  `defaultToTimestamp`; unset bounds search from the beginning up to now. A
  trace older than the listing is still readable by its id, as long as one of
  its spans comes from that service.
* **Missing paths:** a service Jaeger does not know, a trace id that is not 16
  or 32 hex digits, and a trace without a span from the addressed service are
  reported as missing.
* **Sizes:** every listed file has an exact size, so `ls -l`, `du` and `stat`
  work without reading the files.

## VFS.md

The [VFS.md](https://docs.mirage.strukto.ai/home/setup/vfs-md.md) an agent reads with Jaeger mounted at `/<path>`.

> [tab] Rendered
>
> **Virtual Filesystem**
>
> | Path | Description |
> | - | - |
> | `/<path>` | `jaeger`, read |
>
> **VFS Layout**
>
> **`/<path>`**
>
> ```text theme={null}
> /<path>
>   services/
>     <service-name>/
>       operations.json
>       traces/
>         <trace-id>.json
> ```
>
> **Supported Unix Commands for VFS**
>
> Unix commands work on each path as on a local filesystem, as far as the path supports them:
>
> | Path | Supported |
> | - | - |
> | `/<path>` | Commands that read files (`ls`, `cat`, `grep`, `find`, `jq` and the rest). |
>
> **Limitations of Unix Commands for VFS**
>
> Where a path differs from a local filesystem:
>
> | Path | Limitations |
> | - | - |
> | `/<path>` | Read only: no command changes files. `grep -r`, `find` and `du` stop after 1000 files; a glob matching more, `tar -c`, `cp -r` and `rm -r` are refused. |
>
> Run `man <cmd>` or `<cmd> --help` for one command's usage.

> [tab] Raw
>
> ````markdown theme={null}
> ---
> name: workspace-filesystem
> description: The virtual filesystem layout of this workspace.
> ---
>
> # Virtual Filesystem
>
> | Path | Description |
> | --- | --- |
> | `/<path>` | `jaeger`, read |
>
> ## VFS Layout
>
> ### `/<path>`
>
> ```text
> /<path>
>   services/
>     <service-name>/
>       operations.json
>       traces/
>         <trace-id>.json
> ```
>
> ## Supported Unix Commands for VFS
>
> Unix commands work on each path as on a local filesystem, as far as the path supports them:
>
> | Path | Supported |
> | --- | --- |
> | `/<path>` | Commands that read files (`ls`, `cat`, `grep`, `find`, `jq` and the rest). |
>
> ## Limitations of Unix Commands for VFS
>
> Where a path differs from a local filesystem:
>
> | Path | Limitations |
> | --- | --- |
> | `/<path>` | Read only: no command changes files. `grep -r`, `find` and `du` stop after 1000 files; a glob matching more, `tar -c`, `cp -r` and `rm -r` are refused. |
>
> Run `man <cmd>` or `<cmd> --help` for one command's usage.
> ````


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.