0.69.0 • Published 1 week ago

@opentelemetry/instrumentation-koa

Licence

Apache-2.0

Version

0.69.0

Deps

Size

53 kB

Vulns

Weekly

Stars

917

Summary Dependency Versions

OpenTelemetry Koa Instrumentation for Node.js

This module provides automatic instrumentation for the Koa module.

If total installation size is not constrained, it is recommended to use the @opentelemetry/auto-instrumentations-node bundle with @opentelemetry/sdk-node for the most seamless instrumentation experience.

Compatible with OpenTelemetry JS API and SDK 1.0+.

Status

Maturity	Component Owner	Compatibility
Unmaintained	N/A	API 1.0+ SDK 1.0+

Installation

npm install --save @opentelemetry/instrumentation-koa

Supported Versions

koa versions >=2.0.0 <4
@koa/router versions >=8.0.0

Usage

OpenTelemetry Koa Instrumentation allows the user to automatically collect trace data and export them to their backend of choice, to give observability to distributed systems.

const { NodeSDK } = require('@opentelemetry/sdk-node');
const { KoaInstrumentation } = require('@opentelemetry/instrumentation-koa');

const sdk = new NodeSDK({
  instrumentations: [
    new KoaInstrumentation(),
  ],
});
sdk.start();
process.once('beforeExit', async () => { await sdk.shutdown(); });

See examples/koa for a short example using both Koa and @koa/router.

Note that generator-based middleware are deprecated and won't be instrumented.

Koa Instrumentation Options

Options	Type	Example	Description
`ignoreLayersType`	`KoaLayerType[]`	`['middleware']`	Ignore layers of specified type.
`requestHook`	`KoaRequestCustomAttributeFunction`	`(span, info) => {}`	Function for adding custom attributes to Koa middleware layers. Receives params: `Span, KoaRequestInfo`.

ignoreLayersType accepts an array of KoaLayerType which can take the following string values:

router,
middleware.

Using `requestHook`

Instrumentation configuration accepts a custom "hook" function which will be called for every instrumented Koa middleware layer involved in a request. Custom attributes can be set on the span or run any custom logic per layer.

NOTE: KoaRequestInfo.context and KoaRequestInfo.middlewareLayer are typed as any. If you want type support make sure you have @types/koa and @types/koa__router installed then you can use the following type definitions:

import { KoaInstrumentation } from "@opentelemetry/instrumentation-koa"
import type { Middleware, ParameterizedContext, DefaultState } from 'koa';
import type { RouterParamContext } from '@koa/router';

type KoaContext = ParameterizedContext<DefaultState, RouterParamContext>;
type KoaMiddleware = Middleware<DefaultState, KoaContext>;

const koaInstrumentation = new KoaInstrumentation({
  requestHook: function (span: Span, info: KoaRequestInfo<KoaContext, KoaMiddleware>) {
    span.setAttribute(
      'http.method',
      info.context.request.method
    )
  }
});

Koa Packages

This package provides automatic tracing for middleware added using either the core koa package or the @koa/router package.

Useful links

For more information on OpenTelemetry, visit: https://opentelemetry.io/
For more about OpenTelemetry JavaScript: https://github.com/open-telemetry/opentelemetry-js
For help or feedback on this project, join us in GitHub Discussions