@elastic/mockotlpserver
A mock OTLP (OpenTelemetry Protocol) server/receiver for development and testing.
mockotlpserver starts HTTP and gRPC servers (on the default OTLP ports) for
receiving OTLP requests. The data in those requests are printed to the
console. Various output formats are supported.
It also supports being run from Node.js code. This is used in the "../opentelemetry-node" package to assist with testing. A test is of the form:
- start the mockotlpserver
- run an instrumented script
- get the received OTLP data from the mock server and make assertions on that data.
CLI Usage
To use the mock server, first start the server. You can start it via npx,
if you use that:
npx @elastic/mockotlpserver
npx @elastic/mockotlpserver --help
or via the published ghcr.io/elastic/elastic-otel-node/mockotlpserver Docker image:
docker run --rm -it -p 4317:4317 -p 4318:4318 --name mockotlpserver \
ghcr.io/elastic/elastic-otel-node/mockotlpserver:latest
Then, send OTLP data to it.
By default, mockotlpserver will output received OTLP data in two forms:
inspectformat: Uses Node.js'sutil.inspect()(used under the hood forconsole.log). This shows the complete object structure of the received data.summaryformat: This is a custom text format that attempts to show a brief/relevant summary of the data. This format is currently more refined for traces and somewhat for logs / events. For metrics, the summary output is poor.
For example, here is the output when receiving telemetry data from a small script that creates an HTTP server and makes a single request. (This example uses the Elastic Distribution of OpenTelemetry Node.js for instrumentation, the upstream OpenTelemetry Node SDK could be used as well.)
git clone [email protected]:elastic/elastic-otel-node.git
cd elastic-otel-node
npm run ci-all
cd examples/
node -r @elastic/opentelemetry-node simple-http-request.js
mockotlpserver console output
% node lib/cli.js
{"name":"mockotlpserver","level":30,"msg":"OTLP/HTTP listening at http://[::1]:4318/","time":"2024-01-11T22:18:49.017Z"}
{"name":"mockotlpserver","level":30,"msg":"OTLP/HTTP listening at http://localhost:4317/","time":"2024-01-11T22:18:49.025Z"}
ExportTraceServiceRequest {
resourceSpans: [
ResourceSpans {
scopeSpans: [
ScopeSpans {
spans: [
Span {
attributes: [
KeyValue { key: 'http.url', value: AnyValue { stringValue: 'http://localhost:3000/' } },
KeyValue { key: 'http.host', value: AnyValue { stringValue: 'localhost:3000' } },
KeyValue { key: 'net.host.name', value: AnyValue { stringValue: 'localhost' } },
KeyValue { key: 'http.method', value: AnyValue { stringValue: 'GET' } },
KeyValue { key: 'http.scheme', value: AnyValue { stringValue: 'http' } },
KeyValue { key: 'http.target', value: AnyValue { stringValue: '/' } },
KeyValue { key: 'http.flavor', value: AnyValue { stringValue: '1.1' } },
KeyValue { key: 'net.transport', value: AnyValue { stringValue: 'ip_tcp' } },
KeyValue { key: 'net.host.ip', value: AnyValue { stringValue: '::1' } },
KeyValue { key: 'net.host.port', value: AnyValue { intValue: Long { low: 3000, high: 0, unsigned: false } } },
KeyValue { key: 'net.peer.ip', value: AnyValue { stringValue: '::1' } },
KeyValue { key: 'net.peer.port', value: AnyValue { intValue: Long { low: 61855, high: 0, unsigned: false } } },
KeyValue { key: 'http.status_code', value: AnyValue { intValue: Long { low: 200, high: 0, unsigned: false } } },
KeyValue { key: 'http.status_text', value: AnyValue { stringValue: 'OK' } }
],
events: [],
links: [],
traceId: Buffer(16) [Uint8Array] [
128, 35, 86, 43, 203,
245, 130, 92, 63, 188,
74, 232, 155, 123, 212,
222
],
spanId: Buffer(8) [Uint8Array] [
34, 107, 247, 13,
140, 202, 136, 107
],
parentSpanId: Buffer(8) [Uint8Array] [
240, 107, 26, 226,
101, 131, 149, 15
],
name: 'GET',
kind: 2,
startTimeUnixNano: Long { low: 448057536, high: 396978934, unsigned: true },
endTimeUnixNano: Long { low: 452218144, high: 396978934, unsigned: true },
droppedAttributesCount: 0,
droppedEventsCount: 0,
droppedLinksCount: 0,
status: Status { code: 0 }
},
Span {
attributes: [
KeyValue { key: 'http.url', value: AnyValue { stringValue: 'http://localhost:3000/' } },
KeyValue { key: 'http.method', value: AnyValue { stringValue: 'GET' } },
KeyValue { key: 'http.target', value: AnyValue { stringValue: '/' } },
KeyValue { key: 'net.peer.name', value: AnyValue { stringValue: 'localhost' } },
KeyValue { key: 'http.host', value: AnyValue { stringValue: 'localhost:3000' } },
KeyValue { key: 'net.peer.ip', value: AnyValue { stringValue: '::1' } },
KeyValue { key: 'net.peer.port', value: AnyValue { intValue: Long { low: 3000, high: 0, unsigned: false } } },
KeyValue { key: 'http.response_content_length_uncompressed', value: AnyValue { intValue: Long { low: 4, high: 0, unsigned: false } } },
KeyValue { key: 'http.status_code', value: AnyValue { intValue: Long { low: 200, high: 0, unsigned: false } } },
KeyValue { key: 'http.status_text', value: AnyValue { stringValue: 'OK' } },
KeyValue { key: 'http.flavor', value: AnyValue { stringValue: '1.1' } },
KeyValue { key: 'net.transport', value: AnyValue { stringValue: 'ip_tcp' } }
],
events: [],
links: [],
traceId: Buffer(16) [Uint8Array] [
128, 35, 86, 43, 203,
245, 130, 92, 63, 188,
74, 232, 155, 123, 212,
222
],
spanId: Buffer(8) [Uint8Array] [
240, 107, 26, 226,
101, 131, 149, 15
],
name: 'GET',
kind: 3,
startTimeUnixNano: Long { low: 439057536, high: 396978934, unsigned: true },
endTimeUnixNano: Long { low: 454517668, high: 396978934, unsigned: true },
droppedAttributesCount: 0,
droppedEventsCount: 0,
droppedLinksCount: 0,
status: Status { code: 0 }
}
],
scope: InstrumentationScope { attributes: [], name: '@opentelemetry/instrumentation-http', version: '0.45.1' }
}
],
resource: Resource {
attributes: [
KeyValue { key: 'service.name', value: AnyValue { stringValue: 'unknown-node-service' } },
KeyValue { key: 'telemetry.sdk.language', value: AnyValue { stringValue: 'nodejs' } },
KeyValue { key: 'telemetry.sdk.name', value: AnyValue { stringValue: 'opentelemetry' } },
KeyValue { key: 'telemetry.sdk.version', value: AnyValue { stringValue: '1.18.1' } },
KeyValue { key: 'process.pid', value: AnyValue { intValue: Long { low: 82408, high: 0, unsigned: false } } },
KeyValue { key: 'process.executable.name', value: AnyValue { stringValue: 'node' } },
KeyValue { key: 'process.executable.path', value: AnyValue { stringValue: '/Users/trentm/.nvm/versions/node/v18.18.2/bin/node' } },
KeyValue {
key: 'process.command_args',
value: AnyValue {
arrayValue: ArrayValue {
values: [
AnyValue { stringValue: '/Users/trentm/.nvm/versions/node/v18.18.2/bin/node' },
AnyValue { stringValue: '-r' },
AnyValue { stringValue: '@elastic/opentelemetry-node' },
AnyValue { stringValue: '/Users/trentm/el/elastic-otel-node/examples/simple-http-request.js' }
]
}
}
},
KeyValue { key: 'process.runtime.version', value: AnyValue { stringValue: '18.18.2' } },
KeyValue { key: 'process.runtime.name', value: AnyValue { stringValue: 'nodejs' } },
KeyValue { key: 'process.runtime.description', value: AnyValue { stringValue: 'Node.js' } },
KeyValue { key: 'process.command', value: AnyValue { stringValue: '/Users/trentm/el/elastic-otel-node/examples/simple-http-request.js' } },
KeyValue { key: 'process.owner', value: AnyValue { stringValue: 'trentm' } },
KeyValue { key: 'host.name', value: AnyValue { stringValue: 'pink.local' } },
KeyValue { key: 'host.arch', value: AnyValue { stringValue: 'amd64' } },
KeyValue { key: 'host.id', value: AnyValue { stringValue: 'DF529BD4-274A-53F1-A84E-7F85AFD59258' } }
],
droppedAttributesCount: 0
}
}
]
}
------ trace 802356 (2 spans) ------
span f06b1a "GET" (15.5ms, SPAN_KIND_CLIENT, GET http://localhost:3000/ -> 200)
+9ms `- span 226bf7 "GET" (4.2ms, SPAN_KIND_SERVER, GET http://localhost:3000/ -> 200)
In particular, note the "trace summary" output that shows a line for each span, showing parent/child relationships:
------ trace 802356 (2 spans) ------
span f06b1a "GET" (15.5ms, SPAN_KIND_CLIENT, GET http://localhost:3000/ -> 200)
+9ms `- span 226bf7 "GET" (4.2ms, SPAN_KIND_SERVER, GET http://localhost:3000/ -> 200)
Different OTLP protocols
By default the OpenTelemetry JS NodeSDK uses the OTLP/proto protocol. The
other flavours of OTLP are supported by mockotlpserver as well. Use the
OTEL_EXPORTER_OTLP_PROTOCOL to tell the NodeSDK to use a different protocol.
For example:
cd ../../examples
OTEL_EXPORTER_OTLP_PROTOCOL=http/json node -r @elastic/opentelemetry-node simple-http-request.js
OTEL_EXPORTER_OTLP_PROTOCOL=grpc node -r @elastic/opentelemetry-node simple-http-request.js
If you look carefully, you can see some differences in the representation of some fields (startTimeUnixNano, traceId, spanId, etc.).
WARNING: At the time of writing the Elastic OTel Node.js SDK distro only
supports the OTLP/proto flavour for metrics and logs exporting -- the
OTEL_EXPORTER_OTLP_PROTOCOL setting will be ignored. It is only the trace
exporter that currently honours that setting.
Different mockotlpserver printers
There are a few groups of "printers" that format and write received OTLP data to the console:
inspect- Use Node.js'sutil.inspectto dump a complete and coloured representation.json,json2- Show a (somewhat normalized) JSON representation. The2means 2-space indentation.summary- An opinionated compact summary of the data.
Each of these printers can be limited to a particular signal by prefixing with
the signal. E.g. node lib/cli.js -o logs-inspect,summary will show full
"inspect" output for received Logs OTLP requests and summary output for all
signals.
Some notes on particular printers follow.
json, json2
node lib/cli.js -o json # 0-space indentation, i.e. compact
node lib/cli.js -o json2 # 2-space indentation
The JSON-related printers do some normalization of fields for convenience.
attributesare converted to a mapping for brevitytraceId,spanId,parentSpanIdare converted to a hex valuestartTimeUnixNano,endTimeUnixNanoare converted to a string of a 64-bit integer (JavaScript's JSON.stringify cannot handle large 64-bit integers, so using Number can lose precision.)- Note: some others not mentioned here. See "lib/normalize.js" for details.
You can run node lib/cli.js -o inspect,json to compare the raw and normalized
JSON forms.
trace-summary
This printer converts OTLP trace spans into a sort of "waterfall" representation of the trace. The parent/child relationships are shown, along with some span timing and other details.
# server
node lib/cli.js -o inspect,trace-summary
# example client
(cd ../../examples; node -r @elastic/opentelemetry-node simple-http-request.js)
# waterfall rendering
------ trace 299229 (2 spans) ------
span 090dfe "GET" (14.5ms, SPAN_KIND_CLIENT, GET http://localhost:3000/ -> 200)
+9ms `- span 90acc7 "GET" (3.4ms, SPAN_KIND_SERVER, GET http://localhost:3000/ -> 200)
- The leading gutter shows the start time offset from the preceding span.
`-markers show parent/child relationships.- Span and trace IDs (e.g.
299229,090dfe) are trimmed to prefix for brevity.
Module usage
The mock OTLP server can also be used in Node.js code (e.g. in a test suite).
const {MockOtlpServer} = require('@elastic/mockotlpserver');
const otlpServer = new MockOtlpServer({
onTrace: (trace) => { /* ... */ },
// ... see code comment for other options.
});
otlpServer.start();
// Run code that sends telemetry via OTLP...
otlpServer.close();
See runTestFixtures() in "../opentelemetry-node/test/testutils.js" for a
more complete example.