@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 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
- # Temporary Holding Version
1
+ # @crvouga/mockingbird-service-tempo
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
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 | ✅ | |