Skip to content

Latest commit

 

History

History

mockotlpserver

README.md

@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:

  1. start the mockotlpserver
  2. run an instrumented script
  3. 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

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:

  1. inspect format: Uses Node.js's util.inspect() (used under the hood for console.log). This shows the complete object structure of the received data.
  2. summary format: 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 and 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's util.inspect to dump a complete and coloured representation.
  • json, json2 - Show a (somewhat normalized) JSON representation. The 2 means 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.

  • attributes are converted to a mapping for brevity
  • traceId, spanId, parentSpanId are converted to a hex value
  • startTimeUnixNano, endTimeUnixNano are 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.