@crvouga/mockingbird-service-tempo 0.0.0-stage → 0.2.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +15 -0
- package/DISCOVERY.md +78 -0
- package/README.md +245 -2
- package/SUPPORT.md +14 -0
- package/dist/chunk-7MQGS5MD.js +975 -0
- package/dist/chunk-7MQGS5MD.js.map +7 -0
- package/dist/chunk-Z7J6TZKJ.js +6730 -0
- package/dist/chunk-Z7J6TZKJ.js.map +7 -0
- package/dist/cli.js +19 -0
- package/dist/cli.js.map +7 -0
- package/dist/index.d.ts +1589 -0
- package/dist/index.js +55 -0
- package/dist/index.js.map +7 -0
- package/dist/server.d.ts +2187 -0
- package/dist/server.js +12 -0
- package/dist/server.js.map +7 -0
- package/openapi.yaml +843 -0
- package/package.json +128 -4
package/CHANGELOG.md
ADDED
|
@@ -0,0 +1,15 @@
|
|
|
1
|
+
# Changelog — @crvouga/mockingbird-service-tempo
|
|
2
|
+
|
|
3
|
+
## 0.2.0 (2026-10-12)
|
|
4
|
+
|
|
5
|
+
### Features
|
|
6
|
+
|
|
7
|
+
- unify the emulator control plane ([2068547](https://github.com/crvouga/mockingbird/commit/2068547bedde4e2e2331c1657c1a78120e84428b))
|
|
8
|
+
|
|
9
|
+
### Dependencies
|
|
10
|
+
|
|
11
|
+
- `@crvouga/mockingbird-service-sqlite`
|
|
12
|
+
|
|
13
|
+
## 0.1.0 (2026-10-10)
|
|
14
|
+
|
|
15
|
+
Initial release.
|
package/DISCOVERY.md
ADDED
|
@@ -0,0 +1,78 @@
|
|
|
1
|
+
# @crvouga/mockingbird-service-tempo discovery
|
|
2
|
+
|
|
3
|
+
This is the installed-package index for coding agents and tooling. All relative links resolve
|
|
4
|
+
inside `node_modules/@crvouga/mockingbird-service-tempo/`; no repository checkout is needed to discover the emulator's
|
|
5
|
+
supported surface or documented behavior.
|
|
6
|
+
|
|
7
|
+
## Capability and behavior sources
|
|
8
|
+
|
|
9
|
+
| Question | Authoritative file | What it contains |
|
|
10
|
+
| --- | --- | --- |
|
|
11
|
+
| Behaviour and integration | [`README.md`](README.md) | Routes, state transitions, auth, webhooks, controls, presets and deliberate omissions. |
|
|
12
|
+
| Exact capabilities | [`SUPPORT.md`](SUPPORT.md) | Supported, unsupported and parity-covered operations or commands, including reasons for gaps. |
|
|
13
|
+
| Wire contract | [`openapi.yaml`](openapi.yaml) | Machine-readable paths, methods, schemas, responses and parity annotations. |
|
|
14
|
+
| Public API | [`dist/index.d.ts`](dist/index.d.ts) | The installed package's exact TypeScript exports and signatures. |
|
|
15
|
+
| Package metadata | [`package.json`](package.json) | Runtime/entry-point claims, vendor links, parity scope/tier and `mockingbird.discovery`. |
|
|
16
|
+
|
|
17
|
+
Read these together: the contract/capability matrix says *what* is available, while the README
|
|
18
|
+
defines stateful behavior, lifecycle rules, test controls, and intentional oracle differences.
|
|
19
|
+
If prose and an executable surface disagree, report a parity mismatch instead of adding a
|
|
20
|
+
consumer-side workaround.
|
|
21
|
+
|
|
22
|
+
## Parity and oracle
|
|
23
|
+
|
|
24
|
+
- Declared parity surface: **OTLP trace ingest, TraceQL search, trace lookup and tag names**.
|
|
25
|
+
- Parity tier: **cold** (the repository controls when live checks run).
|
|
26
|
+
- Oracle: **Live vendor API or sandbox**.
|
|
27
|
+
- Repository command: `bun run parity:service -- tempo`.
|
|
28
|
+
- Evidence model: Run from a Mockingbird checkout; credentials come only from .env.local or GitHub Actions secrets. Missing credentials exit 2.
|
|
29
|
+
|
|
30
|
+
The npm package contains evidence summaries and the exact contract, not credentials or the
|
|
31
|
+
repository-only parity harness. Self-parity/property and acceptance tests run in the Mockingbird
|
|
32
|
+
repository; live parity is an additional oracle check, not a substitute for the packaged matrix.
|
|
33
|
+
|
|
34
|
+
## Runtime introspection
|
|
35
|
+
|
|
36
|
+
- `GET /__admin/health`
|
|
37
|
+
- `GET /__admin`
|
|
38
|
+
- `GET /__admin/controls`
|
|
39
|
+
- `GET /__admin/state`
|
|
40
|
+
- `GET /__admin/requests`
|
|
41
|
+
- `GET /__admin/metrics`
|
|
42
|
+
- `GET /__admin/faults/presets`
|
|
43
|
+
- `GET /__admin/ui`
|
|
44
|
+
|
|
45
|
+
For HTTP services, use `x-mockingbird-namespace` (or the documented credential/path carrier) so
|
|
46
|
+
parallel tests do not share state. Admin state, journal, metrics and fault-preset endpoints are
|
|
47
|
+
designed for assertions and diagnosis by consuming test suites.
|
|
48
|
+
|
|
49
|
+
## Admin controls
|
|
50
|
+
|
|
51
|
+
Every HTTP emulator takes the same controls, and each means the same thing at boot
|
|
52
|
+
(`createRuntime({ adminControls })`, `serve --admin-controls`), over `/__admin`, and in a request header:
|
|
53
|
+
|
|
54
|
+
| Control | Admin API | Request header | Interface |
|
|
55
|
+
| --- | --- | --- | --- |
|
|
56
|
+
| Isolate state by key | `GET /__admin/namespaces` | `x-mockingbird-namespace: <key>` | [Namespaces](https://mockingbird.chrisvouga.dev/docs/admin-controls/namespaces) |
|
|
57
|
+
| Reset to boot | `POST /__admin/reset` | `x-mockingbird-reset: true` | [Reset](https://mockingbird.chrisvouga.dev/docs/admin-controls/reset) |
|
|
58
|
+
| Snapshot and restore | `POST /__admin/snapshots`, `POST /__admin/snapshots/<id>/restore` | `x-mockingbird-snapshot: <name>`, `x-mockingbird-restore: <name>` | [Snapshot and restore](https://mockingbird.chrisvouga.dev/docs/admin-controls/snapshot-and-restore) |
|
|
59
|
+
| Move the clock | `POST /__admin/clock` | `x-mockingbird-time: <instant>`, `x-mockingbird-advance: <duration>` | [Clock](https://mockingbird.chrisvouga.dev/docs/admin-controls/clock) |
|
|
60
|
+
| Read or branch from old state | `GET /__admin/timeline` | `x-mockingbird-at: <checkpoint>`, `x-mockingbird-branch: <name>` | [Checkpoints and branches](https://mockingbird.chrisvouga.dev/docs/admin-controls/checkpoints-and-branches) |
|
|
61
|
+
| Inject a fault | `POST /__admin/faults` | `x-mockingbird-fault: <fault>` | [Faults](https://mockingbird.chrisvouga.dev/docs/admin-controls/faults) |
|
|
62
|
+
| Latency and timeouts | `PUT /__admin/latency` | `x-mockingbird-delay: <duration>`, `x-mockingbird-timeout: <duration>` | [Latency and timeouts](https://mockingbird.chrisvouga.dev/docs/admin-controls/latency-and-timeouts) |
|
|
63
|
+
| Replay from a seed | `PUT /__admin/controls` | `x-mockingbird-seed: <seed>` | [Seed and determinism](https://mockingbird.chrisvouga.dev/docs/admin-controls/seed-and-determinism) |
|
|
64
|
+
| See what happened | `GET /__admin/requests`, `GET /__admin/state` | | [Journal, metrics and state](https://mockingbird.chrisvouga.dev/docs/admin-controls/journal-and-state) |
|
|
65
|
+
|
|
66
|
+
`GET /__admin` lists every route and header with a one-line summary, and `GET /__admin/controls`
|
|
67
|
+
is the namespace's current control document. The same seed and the same requests give the same
|
|
68
|
+
bytes. Setting controls as an emulator starts is [Boot](https://mockingbird.chrisvouga.dev/docs/admin-controls/boot); every route and header is in
|
|
69
|
+
the [Reference](https://mockingbird.chrisvouga.dev/docs/admin-controls/reference). The full guide: <https://mockingbird.chrisvouga.dev/docs/admin-controls>.
|
|
70
|
+
|
|
71
|
+
## Report a mismatch or missing capability
|
|
72
|
+
|
|
73
|
+
Follow the [agent reporting contract](https://github.com/crvouga/mockingbird/blob/main/docs/REPORTING_ISSUES.md). Include package version,
|
|
74
|
+
operation/command, a minimal redacted request, actual emulator result, expected oracle result or vendor
|
|
75
|
+
documentation, and whether the mismatch appears in the matrix. Never include keys, tokens,
|
|
76
|
+
customer data, prompts, PHI, card data, or unredacted recordings.
|
|
77
|
+
|
|
78
|
+
Service key: `tempo`.
|
package/README.md
CHANGED
|
@@ -1,3 +1,246 @@
|
|
|
1
|
-
#
|
|
1
|
+
# @crvouga/mockingbird-service-tempo
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
> Local emulators. Real API contracts. Part of [Mockingbird](https://github.com/crvouga/mockingbird).
|
|
4
|
+
|
|
5
|
+
Stateful emulator of **Grafana Tempo** for test suites: the OTLP/HTTP trace receiver
|
|
6
|
+
(`POST /v1/traces`, JSON and protobuf) and the query routes a trace reader calls (TraceQL search,
|
|
7
|
+
trace by id, tag names), over one store. A test exports spans the way its application does and
|
|
8
|
+
reads them back with the requests its production reader sends, with no Docker and no Tempo.
|
|
9
|
+
|
|
10
|
+
- Operation coverage: [SUPPORT.md](https://github.com/crvouga/mockingbird/blob/main/packages/service/tempo/SUPPORT.md)
|
|
11
|
+
- Status: **work in progress**. Tempo publishes no OpenAPI document and no instance was
|
|
12
|
+
available while this was written, so the contract (`openapi.yaml`) follows Grafana's
|
|
13
|
+
[HTTP API reference](https://grafana.com/docs/tempo/latest/api_docs/) and Tempo's source at
|
|
14
|
+
v3.1.0. [What was verified, and how](#what-was-verified-and-how) lists every detail that could
|
|
15
|
+
not be confirmed.
|
|
16
|
+
|
|
17
|
+
## Install
|
|
18
|
+
|
|
19
|
+
```bash
|
|
20
|
+
npm install -D @crvouga/mockingbird-service-tempo
|
|
21
|
+
```
|
|
22
|
+
|
|
23
|
+
ESM only. Node >= 22 or Bun >= 1.2. No native dependencies. Serve it with
|
|
24
|
+
`npx mockingbird-tempo serve`, `createServer` from `./server` (Node), or `createRuntime` with any
|
|
25
|
+
Fetch server.
|
|
26
|
+
|
|
27
|
+
## Usage
|
|
28
|
+
|
|
29
|
+
Tempo listens on two ports (4318 for OTLP, 3200 for queries); the emulator serves both from one
|
|
30
|
+
origin. Point the exporter's endpoint and the reader's Tempo URL at it:
|
|
31
|
+
|
|
32
|
+
```bash
|
|
33
|
+
npx mockingbird-tempo serve --port 8930
|
|
34
|
+
# OTEL_EXPORTER_OTLP_ENDPOINT=http://127.0.0.1:8930 (the exporter posts /v1/traces)
|
|
35
|
+
# TEMPO_URL=http://127.0.0.1:8930 (the reader calls /api/…)
|
|
36
|
+
|
|
37
|
+
# Grafana Cloud style credentials, and tenants:
|
|
38
|
+
npx mockingbird-tempo serve --basic-auth 123456:fixture-token --multitenancy
|
|
39
|
+
```
|
|
40
|
+
|
|
41
|
+
```ts
|
|
42
|
+
import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-http"
|
|
43
|
+
import { resourceFromAttributes } from "@opentelemetry/resources"
|
|
44
|
+
import { BasicTracerProvider, SimpleSpanProcessor } from "@opentelemetry/sdk-trace-base"
|
|
45
|
+
import { createServer } from "@crvouga/mockingbird-service-tempo/server"
|
|
46
|
+
|
|
47
|
+
const server = await createServer()
|
|
48
|
+
|
|
49
|
+
// The OpenTelemetry SDK your application already uses. Only the exporter's URL changes
|
|
50
|
+
// (the protobuf exporter works the same way).
|
|
51
|
+
const provider = new BasicTracerProvider({
|
|
52
|
+
resource: resourceFromAttributes({ "service.name": "checkout" }),
|
|
53
|
+
spanProcessors: [new SimpleSpanProcessor(new OTLPTraceExporter({ url: `${server.url}/v1/traces` }))],
|
|
54
|
+
})
|
|
55
|
+
const span = provider.getTracer("checkout").startSpan("POST /checkout", {
|
|
56
|
+
startTime: new Date(1_700_000_000_000),
|
|
57
|
+
attributes: { "user.id": "user-1" },
|
|
58
|
+
})
|
|
59
|
+
span.end(new Date(1_700_000_001_500))
|
|
60
|
+
await provider.forceFlush()
|
|
61
|
+
|
|
62
|
+
// What the trace reader sends (Tempo's query API is plain HTTP).
|
|
63
|
+
const q = encodeURIComponent('{ .user.id = "user-1" }')
|
|
64
|
+
const search = await fetch(`${server.url}/api/search?q=${q}&start=1699999990&end=1700000010&limit=50`)
|
|
65
|
+
const { traces } = (await search.json()) as { traces: { traceID: string }[] }
|
|
66
|
+
const trace = await fetch(`${server.url}/api/traces/${traces[0]?.traceID}`)
|
|
67
|
+
|
|
68
|
+
await provider.shutdown()
|
|
69
|
+
await server.close()
|
|
70
|
+
```
|
|
71
|
+
|
|
72
|
+
### Routes
|
|
73
|
+
|
|
74
|
+
| Route | Behaviour |
|
|
75
|
+
| --- | --- |
|
|
76
|
+
| `POST /v1/traces` | An `ExportTraceServiceRequest` as `application/json` or `application/x-protobuf` (gzip accepted). Success is 200 with `{"partialSuccess":{}}` for JSON and an empty protobuf message for protobuf. Errors are `google.rpc.Status` in the request's encoding: 400 code 3 for a payload that does not decode, `trace ids must be 128 bit, received N bits` and `span ids must be 64 bit and not all zero, received N bits` for ids Tempo's distributor refuses (the whole export is refused, nothing is stored). Any other content type is 415 `415 unsupported media type, supported: [application/json, application/x-protobuf]` as plain text. An export without spans is accepted before any other check. A span id already stored for the trace is replaced. |
|
|
77
|
+
| `GET /api/search` | `q` (TraceQL, see below), `start`/`end` (epoch seconds), `limit` (default 20), `spss` (spans per span set, default 3, at most 100). Answers `{traces: [...], metrics: {...}}`; each trace has `traceID`, `rootServiceName`, `rootTraceName`, `startTimeUnixNano` (nanoseconds, a decimal string), `durationMs` (a number), `spanSet`/`spanSets` (the matched spans: `spanID`, `startTimeUnixNano`, `durationNanos`, and the attributes the query compared; `matched` counts all of them) and `serviceStats`. No match is `{"traces": []}`. Newest trace first. With both `start` and `end` (non-zero), a trace is returned when it overlaps the window: it starts at or before `end` and ends at or after `start`, both inclusive to the nanosecond; with either missing no window applies, as in Tempo. With no `q` every trace in the window is returned. |
|
|
78
|
+
| `GET /api/traces/{traceId}` | The trace as Tempo marshals it: `{"batches": [{resource, scopeSpans: [{scope, spans}]}]}`. This is **not** OTLP/JSON: `traceId`, `spanId` and `parentSpanId` are base64, `kind` and `status.code` are enum names (`SPAN_KIND_SERVER`, `STATUS_CODE_ERROR`), 64-bit integers (times, `intValue`) are decimal strings, zero values are omitted, and every span has a `status` object. A trace id shorter than 32 hex characters is left-padded. Unknown trace: 404 with an empty body. Not hex: 400 `trace IDs can only contain hex characters: invalid character 'x' at position N`. |
|
|
79
|
+
| `GET /api/v2/search/tags` | `scope` = `span`, `resource`, `event`, `link`, `instrumentation`, `intrinsic`, or absent/`none` for all of them. Answers `{scopes: [{name, tags}], metrics}`: attribute names seen on any stored span, each list sorted, a scope with no names left out. A name seen on a single span is listed. `limit` caps each list. Unknown scope: 400 `invalid scope: <scope>`. |
|
|
80
|
+
|
|
81
|
+
Every 400 from the query routes is Tempo's: the error text as the whole body, `text/plain`.
|
|
82
|
+
Search validates in Tempo's order: `invalid start: strconv.ParseUint: parsing "abc": invalid syntax`,
|
|
83
|
+
`invalid limit: must be a positive number`, `http parameter start must be before end. received
|
|
84
|
+
start=10 end=5`, `limit N exceeds max limit M`, then the TraceQL query, the 168 h maximum range
|
|
85
|
+
and `spans per span set exceeds 100. received N`.
|
|
86
|
+
|
|
87
|
+
### TraceQL
|
|
88
|
+
|
|
89
|
+
One spanset filter is evaluated:
|
|
90
|
+
|
|
91
|
+
- `{ }`, `{ true }`, `{ false }`
|
|
92
|
+
- attribute equality: `.name`, `span.name` or `resource.name` (quoted parts such as
|
|
93
|
+
`span."user id"` included) `=` a string, integer, float or boolean
|
|
94
|
+
- `&&` between those; every condition has to hold on the same span
|
|
95
|
+
|
|
96
|
+
An unscoped `.name` reads the span's attribute and falls back to the resource's. Types compare
|
|
97
|
+
exactly, except that integers and floats compare as numbers. An array attribute matches when any
|
|
98
|
+
element does.
|
|
99
|
+
|
|
100
|
+
Anything else is a 400 and never a looser match:
|
|
101
|
+
|
|
102
|
+
- Input Tempo's parser rejects answers with Tempo's wording and position, for example
|
|
103
|
+
`invalid TraceQL query: parse error at line 1, col 3: syntax error: unexpected IDENTIFIER` for
|
|
104
|
+
`{ user.id = "u" }` (the dot is missing).
|
|
105
|
+
- Valid TraceQL outside the subset (`=~`, `!=`, `>`, `||`, intrinsics such as `status` or
|
|
106
|
+
`duration`, `event.`/`link.`/`parent.` scopes, pipelines, spanset operators, hints) answers
|
|
107
|
+
`invalid TraceQL query: <construct> not yet supported (Mockingbird emulates a TraceQL subset)`.
|
|
108
|
+
The first part is the wording Tempo's validator uses for features it lacks; a real Tempo
|
|
109
|
+
evaluates these queries.
|
|
110
|
+
|
|
111
|
+
### Authentication and tenants
|
|
112
|
+
|
|
113
|
+
Tempo itself authenticates nobody; a gateway in front of it does. The emulator plays both:
|
|
114
|
+
|
|
115
|
+
| Setting | Effect |
|
|
116
|
+
| --- | --- |
|
|
117
|
+
| none (default) | A local Tempo: no credentials needed, stray ones ignored. |
|
|
118
|
+
| `bearerTokens` (`--bearer-token`) | `Authorization: Bearer <token>` on ingest and query. |
|
|
119
|
+
| `basicUsers` (`--basic-auth user:password`) | `Authorization: Basic …`, Grafana Cloud style (instance id and access token). |
|
|
120
|
+
| `unauthorized` | The response for missing or wrong credentials: `{status, body, contentType}` with `status` 401 or 403, default 401 `Unauthorized` as plain text. Set it to what your gateway answers. |
|
|
121
|
+
| `multitenancy` (`--multitenancy`) | Tempo's `multitenancy_enabled`: `X-Scope-OrgID` is required and a tenant reads only what it wrote. A query route without the header is 401 `no org id`; an export without it is 503 `{"code":14,"message":"no org id"}`. `a\|b` on a query reads both tenants. Off, the header is ignored. |
|
|
122
|
+
| `leftPadTraceIds` (`--left-pad-trace-ids`) | Tempo's `left_pad_trace_ids`: search answers 32-character trace ids. Off (Tempo's default), leading zeros are trimmed. |
|
|
123
|
+
| `defaultLimit`, `maxLimit` | Search's default (20) and maximum (262144) result count. |
|
|
124
|
+
|
|
125
|
+
Bearer tokens and Basic users can be configured together; a request needs one that matches.
|
|
126
|
+
|
|
127
|
+
### Admin (beyond the standard contract)
|
|
128
|
+
|
|
129
|
+
| Route | Effect |
|
|
130
|
+
| --- | --- |
|
|
131
|
+
| `POST /__admin/traces` | `{resourceSpans: [...], tenant?}`: store an OTLP/JSON export exactly as given, with no credentials, faults or tenant header in the way. A span without `startTimeUnixNano` starts at the emulator clock (`POST /__admin/clock`), and without `endTimeUnixNano` ends there. Answers `{accepted, tenant, traceIds}`. |
|
|
132
|
+
| `GET /__admin/traces` | `{traces: [{tenant, traceID, spanCount, rootServiceName, rootTraceName, startTimeUnixNano, durationMs}]}`, oldest first. `?tenant=` narrows it. |
|
|
133
|
+
| `GET /__admin/spans` | `{spans: [...]}`: the stored spans (hex ids beside the wire shape). `?traceId=`, `?tenant=`. |
|
|
134
|
+
| `GET /__admin/settings`, `PUT /__admin/settings` | The settings above, for the calling namespace. `POST /__admin/reset` returns them to their defaults. |
|
|
135
|
+
|
|
136
|
+
Snapshots (`POST /__admin/snapshots`, `POST /__admin/snapshots/:id/restore`), checkpoints,
|
|
137
|
+
reset, the clock, the request journal and metrics are the standard contract. The journal records
|
|
138
|
+
that an export happened and which trace ids it touched, never span contents.
|
|
139
|
+
|
|
140
|
+
Fault presets (`POST /__admin/faults {"preset": "<name>", "count"?: n}`; `"count": 1` is a
|
|
141
|
+
one-shot; `GET /__admin/faults/presets`): `ingest_unavailable` (503, exporters retry),
|
|
142
|
+
`ingest_rate_limited` (429 `RATE_LIMITED: …`, retried), `ingest_server_error` (500, dropped),
|
|
143
|
+
`ingest_dropped` (the connection dies), `query_unavailable` (503), `query_server_error`
|
|
144
|
+
(500 `internal error`), `query_rate_limited` (429 `too many outstanding requests`),
|
|
145
|
+
`query_timeout` (504 `context deadline exceeded`), `query_dropped`, `unauthorized` (the
|
|
146
|
+
configured 401 on every route). Ingest faults answer `google.rpc.Status` in the request's
|
|
147
|
+
encoding.
|
|
148
|
+
|
|
149
|
+
### Namespaces
|
|
150
|
+
|
|
151
|
+
Parallel workers each get their own store by `x-mockingbird-namespace`, by a
|
|
152
|
+
`/__admin/ns/<name>` prefix on the base URL, or by credential:
|
|
153
|
+
`PUT /__admin/credentials {"credentials": {"<bearer token or Basic username>": "<namespace>"}}`.
|
|
154
|
+
Tenants (`X-Scope-OrgID`) are a separate wall inside a namespace.
|
|
155
|
+
|
|
156
|
+
### What was verified, and how
|
|
157
|
+
|
|
158
|
+
No Tempo instance was available. Each behaviour was read from Grafana's documentation or
|
|
159
|
+
Tempo's source (v3.1.0) and the OpenTelemetry Collector's OTLP receiver (v0.153.0, which Tempo
|
|
160
|
+
embeds):
|
|
161
|
+
|
|
162
|
+
- Search parameters, defaults, validation order and messages: `pkg/api/http.go`
|
|
163
|
+
(`ParseSearchRequest`), `modules/frontend/search_handlers.go`, `search_sharder.go`.
|
|
164
|
+
- Search and tags response fields and JSON types: `pkg/tempopb/tempo.proto` marshalled with gogo
|
|
165
|
+
`jsonpb` defaults (`modules/frontend/combiner/common.go`), and the documented examples.
|
|
166
|
+
- Newest-first ordering, the overlap window, trimmed trace ids, `<root span not yet received>`:
|
|
167
|
+
`pkg/traceql/combine.go`, `tempodb/encoding/vparquet5/block_traceql.go`, `pkg/util/traceid.go`,
|
|
168
|
+
`modules/frontend/combiner/search.go`.
|
|
169
|
+
- `batches`, base64 ids, enum names and span ordering in trace by id; the bodiless 404:
|
|
170
|
+
`pkg/tempopb/trace_utils.go`, `pkg/model/trace/sort.go`,
|
|
171
|
+
`modules/frontend/combiner/trace_by_id.go`, and the example in "Push spans with HTTP".
|
|
172
|
+
- Tag scopes, sorting and the intrinsic list: `pkg/api/search_tags.go`,
|
|
173
|
+
`modules/frontend/tag_handlers.go`, `pkg/search/util.go`, `pkg/collector`.
|
|
174
|
+
- TraceQL tokens, attribute lexing and error positions: `pkg/traceql/lexer.go`, `parse.go`, and
|
|
175
|
+
the expected errors in `parse_test.go`.
|
|
176
|
+
- OTLP responses and errors: the collector's `receiver/otlpreceiver/otlphttp.go` and
|
|
177
|
+
`internal/errors/errors.go`; id checks in `modules/distributor/distributor.go`.
|
|
178
|
+
- `no org id`: dskit `middleware.AuthenticateUser` for queries, Tempo's receiver middleware for
|
|
179
|
+
ingest; cross-tenant reads: "Cross-tenant query federation".
|
|
180
|
+
|
|
181
|
+
**Unverified** (derived, or chosen where the sources say nothing):
|
|
182
|
+
|
|
183
|
+
- The default 401 for wrong credentials. It belongs to whatever gateway fronts Tempo (Grafana
|
|
184
|
+
Cloud's body is not documented); configure `unauthorized` to match yours.
|
|
185
|
+
- Parse-error text beyond the cases in Tempo's parser tests. The emulator never appends goyacc's
|
|
186
|
+
`, expecting …` list except where a test confirms it, and some invalid input that sits outside
|
|
187
|
+
the subset is reported as "not yet supported" instead of as a syntax error.
|
|
188
|
+
- The message text of a 400 for an undecodable export (the status, code 3 and encoding are the
|
|
189
|
+
receiver's; its decoder's wording is not reproduced), and for an id of the wrong length, which
|
|
190
|
+
the receiver rejects before Tempo's distributor would.
|
|
191
|
+
- 503 `no org id` for an export without `X-Scope-OrgID` under multi-tenancy: derived from the
|
|
192
|
+
receiver mapping a plain error to `UNAVAILABLE`, not observed.
|
|
193
|
+
- `metrics` values in search and tags (`inspectedBytes`, `inspectedTraces`): synthetic.
|
|
194
|
+
- `serviceStats`, and which attributes a matched span lists: taken from the engine's source and
|
|
195
|
+
the documented example, not from a live response.
|
|
196
|
+
- Scope order in an unscoped tags response (Tempo's is unordered), the order of traces that start
|
|
197
|
+
at the same nanosecond (the emulator uses the trace id), and which traces a `limit` keeps:
|
|
198
|
+
Tempo "takes the first N results" of a parallel search, the emulator always keeps the newest.
|
|
199
|
+
- The 404 for a path Tempo does not serve (`404 page not found`).
|
|
200
|
+
- Bodies of the query fault presets other than `internal error`, `too many outstanding requests`
|
|
201
|
+
and `context deadline exceeded`.
|
|
202
|
+
|
|
203
|
+
### Deliberately not modelled
|
|
204
|
+
|
|
205
|
+
- The Grafana UI, dashboards, PromQL and metrics; TraceQL metrics (`/api/metrics/query_range`)
|
|
206
|
+
and the metrics-generator.
|
|
207
|
+
- Full TraceQL: only the subset above is evaluated, everything else is a 400.
|
|
208
|
+
- The tag search that predates TraceQL (`tags=`, `minDuration`, `maxDuration`), filtered tag
|
|
209
|
+
names (`q` on the tags route), tag values, and the v1 tags route: refused or absent.
|
|
210
|
+
- `GET /api/v2/traces/{id}` and `Accept: application/protobuf` on query routes: answers are JSON.
|
|
211
|
+
- Block-granular time ranges: `start`/`end` on trace by id and tags are validated, then ignored
|
|
212
|
+
(the emulator is one block that always overlaps).
|
|
213
|
+
- Tail sampling, ingestion limits, retention, compaction, distributed storage, and the delay
|
|
214
|
+
between ingest and searchability: a stored span is visible at once.
|
|
215
|
+
- OTLP/gRPC, Jaeger and Zipkin receivers; OTLP logs and metrics.
|
|
216
|
+
- Administration, provisioning, overrides and cloud resource creation.
|
|
217
|
+
- Span-id de-duplication for Zipkin-style shared ids, and Tempo's root-span and service
|
|
218
|
+
statistics for traces spread over several tenants.
|
|
219
|
+
|
|
220
|
+
Send 64-bit OTLP/JSON values (timestamps, `intValue`) as strings, as exporters do: a JSON number
|
|
221
|
+
past 2^53 loses precision before the emulator sees it. Values that do not fit their protobuf
|
|
222
|
+
width, ids of the wrong length and attribute values nested more than 100 levels deep are refused
|
|
223
|
+
with a 400.
|
|
224
|
+
|
|
225
|
+
## API
|
|
226
|
+
|
|
227
|
+
| Export | Kind | Description |
|
|
228
|
+
| --- | --- | --- |
|
|
229
|
+
| `TempoAPI` | class | The in-process emulator: `fetch(request)`, `reset()`, `inject(payload, tenant?)`, `spans(filter?)`, `traces(tenant?)`. Options: `sqlite`, `now`, `namespace`, `settings`. |
|
|
230
|
+
| `createRuntime` | function | The emulator with the full service contract (health, admin, namespaces, credentials, presets, clock, checkpoints). Options: `settings`, `clock`, `seed`, `adminPrefix`, `adminKey`, `onLog`, `sqlite`. |
|
|
231
|
+
| `TEMPO_PRESETS` | object | Every named fault preset. |
|
|
232
|
+
| `TEMPO_NAMESPACE` | string | The service name, `"tempo"`. |
|
|
233
|
+
| `DEFAULT_SETTINGS` | object | The settings a namespace starts with. |
|
|
234
|
+
| `SINGLE_TENANT` | string | Tempo's tenant when multi-tenancy is off, `"single-tenant"`. |
|
|
235
|
+
| `ORG_ID_HEADER` | string | `"x-scope-orgid"`. |
|
|
236
|
+
| `ROOT_SPAN_NOT_YET_RECEIVED` | string | `rootServiceName` of a trace without a root span. |
|
|
237
|
+
| `INTRINSIC_TAGS` | array | The names under the `intrinsic` tag scope. |
|
|
238
|
+
| `tempoCredential` | function | The bearer token or Basic username of a request (how credentials map to namespaces). |
|
|
239
|
+
| `parseTraceQL`, `matchesSpan`, `TraceQLError` | functions, class | The TraceQL subset: parse a query, test one span's attributes against it, and the error whose message follows `invalid TraceQL query: `. |
|
|
240
|
+
| `decodeSpans`, `validateIds`, `OtlpError` | functions, class | An OTLP/JSON export as spans in Tempo's wire shape, Tempo's id checks, and the error a refused export raises. |
|
|
241
|
+
| `decodeTraceRequest`, `encodeRpcStatus`, `decodeRpcStatus`, `ProtobufError` | functions, class | The protobuf `ExportTraceServiceRequest` decoder and `google.rpc.Status` codec. |
|
|
242
|
+
| `hexToBase64`, `base64ToHex` | functions | Convert ids between OTLP's hex and Tempo's base64. |
|
|
243
|
+
| `document`, `operationIds`, `supportedOperationIds` | values | The OpenAPI contract and its operation ids. |
|
|
244
|
+
| `createServer`, `serveTarget`, `DEFAULT_PORT` (`./server`) | Node | Serve over `node:http`; the `serve` CLI target; port 8930. |
|
|
245
|
+
|
|
246
|
+
Part of [mockingbird](https://github.com/crvouga/mockingbird).
|
package/SUPPORT.md
ADDED
|
@@ -0,0 +1,14 @@
|
|
|
1
|
+
# Grafana Tempo (Mockingbird subset) — operation support
|
|
2
|
+
|
|
3
|
+
Generated from `openapi.yaml`; do not edit by hand.
|
|
4
|
+
|
|
5
|
+
- operations in spec: **4**
|
|
6
|
+
- supported by the emulator: **4**
|
|
7
|
+
- parity enabled: **4**
|
|
8
|
+
|
|
9
|
+
| operationId | route | emulator | parity | notes |
|
|
10
|
+
| --- | --- | --- | --- | --- |
|
|
11
|
+
| `ExportTraces` | `POST /v1/traces` | ✅ supported | ⚠️ unsafe (opt-in) | |
|
|
12
|
+
| `Search` | `GET /api/search` | ✅ supported | ✅ | |
|
|
13
|
+
| `GetTrace` | `GET /api/traces/{traceId}` | ✅ supported | ✅ | |
|
|
14
|
+
| `SearchTagsV2` | `GET /api/v2/search/tags` | ✅ supported | ✅ | |
|