node-zugferd
IntroductionInstallation

General

ParserTemplates

Exchange Networks

TRAFFIQX®

Validators

MustangXSD

Utilities

Magic BytesInstrumentation

Instrumentation

Record OpenTelemetry spans around invoice actions.

The instrumentation plugin records an OpenTelemetry span for every plugin action on the instance. Each span is named after the action it wraps. The tracer scope is node_zugferd, and its version is the version of node-zugferd.

The plugin talks to @opentelemetry/api. Exporting those spans is the application's job. Register a tracer provider before the first invoice call. With no provider, the API discards the spans.

Installation

Install the plugin

@opentelemetry/api is a peer dependency. The plugin reads the tracer from that package, so the application has to depend on it directly.

npm install @node-zugferd/instrumentation@beta @opentelemetry/api

Add the plugin to your instance

Register the plugin on the zugferd() instance. instrumentation() takes no arguments. It spans every plugin on the instance, so each action those plugins expose is traced.

invoicer.ts
import { zugferd } from "node-zugferd";
import { en16931 } from "@node-zugferd/en-16931";
import { instrumentation } from "@node-zugferd/instrumentation";

export const invoicer = zugferd({
  profiles: [en16931],
  plugins: [
    instrumentation(), 
  ],
  // ...
});

Exporting spans

Start a tracer provider before the invoicer runs. A console exporter prints each span while you check the setup. The OpenTelemetry Node.js guide shows how to send the same spans to a collector.

npm install @opentelemetry/sdk-node @opentelemetry/sdk-trace-node
instrumentation.ts
import { NodeSDK } from "@opentelemetry/sdk-node";
import { ConsoleSpanExporter } from "@opentelemetry/sdk-trace-node";

const sdk = new NodeSDK({
  traceExporter: new ConsoleSpanExporter(),
});

sdk.start();

Load that file before the application. Node's --import flag does this:

node --import ./instrumentation.ts ./app.ts

The tracer is read when an action runs. Start the SDK before that call. A provider registered afterwards leaves the earlier actions unrecorded.

Spans

The span name is the path of the action. A nested action uses a dot, so an action called validate inside the xsd namespace is named xsd.validate. Every span sets two attributes:

  • node-zugferd.type is always action.
  • node-zugferd.context is plugin:<id>, where <id> is the id of the plugin that owns the action.

The action is the active span for the length of the call. Other OpenTelemetry instrumentation that runs during it, such as HTTP, is recorded as a child of that action.

A span covers the whole promise. Values an action returns are not spanned on their own. Methods on the invoice that create resolves, such as toXML() or toPDF(), run outside the span.

Errors

A thrown error or a rejected promise is recorded on the span. The span status is set to error, the span ends, and the same error is thrown again. A successful action ends the span with no status code.

Options

instrumentation() takes no arguments. The tracer name, the version, and the span attributes are fixed.


 

llms.txt
Magic Bytes

Check binary attachments against file signatures before an invoice is created.

Allowance

Edit on GitHubPrivacyImprint

On this page

InstallationInstall the pluginAdd the plugin to your instanceExporting spansSpansErrorsOptions

How is this guide?