What is @opentelemetry/instrumentation-koa?
@opentelemetry/instrumentation-koa is an npm package that provides automatic tracing and monitoring for Koa applications using OpenTelemetry. It helps developers gain insights into the performance and behavior of their Koa-based applications by capturing and exporting telemetry data such as traces and metrics.
What are @opentelemetry/instrumentation-koa's main functionalities?
Automatic Tracing
This code sets up automatic tracing for a Koa application. It initializes the OpenTelemetry tracer provider and registers the Koa instrumentation, which automatically captures and exports trace data for incoming HTTP requests.
const { NodeTracerProvider } = require('@opentelemetry/sdk-trace-node');
const { registerInstrumentations } = require('@opentelemetry/instrumentation');
const { KoaInstrumentation } = require('@opentelemetry/instrumentation-koa');
const provider = new NodeTracerProvider();
provider.register();
registerInstrumentations({
instrumentations: [
new KoaInstrumentation(),
],
tracerProvider: provider,
});
const Koa = require('koa');
const app = new Koa();
app.use(async (ctx) => {
ctx.body = 'Hello World';
});
app.listen(3000);
Custom Span Attributes
This code demonstrates how to add custom attributes to spans in a Koa application. The `requestHook` option allows you to modify spans by adding custom attributes, which can be useful for adding additional context to your traces.
const { context, trace } = require('@opentelemetry/api');
const { KoaInstrumentation } = require('@opentelemetry/instrumentation-koa');
const koaInstrumentation = new KoaInstrumentation({
requestHook: (span, ctx) => {
span.setAttribute('http.custom_attribute', 'custom_value');
},
});
const { NodeTracerProvider } = require('@opentelemetry/sdk-trace-node');
const { registerInstrumentations } = require('@opentelemetry/instrumentation');
const provider = new NodeTracerProvider();
provider.register();
registerInstrumentations({
instrumentations: [koaInstrumentation],
tracerProvider: provider,
});
const Koa = require('koa');
const app = new Koa();
app.use(async (ctx) => {
ctx.body = 'Hello World';
});
app.listen(3000);
Other packages similar to @opentelemetry/instrumentation-koa
@opentelemetry/instrumentation-express
@opentelemetry/instrumentation-express provides similar functionality for Express applications. It automatically captures and exports trace data for incoming HTTP requests in Express, allowing developers to monitor and gain insights into their Express-based applications.
@opentelemetry/instrumentation-hapi
@opentelemetry/instrumentation-hapi offers automatic tracing and monitoring for Hapi applications. Like @opentelemetry/instrumentation-koa, it captures and exports telemetry data, but it is specifically designed for Hapi-based applications.
@opentelemetry/instrumentation-fastify
@opentelemetry/instrumentation-fastify provides automatic tracing for Fastify applications. It captures and exports trace data for incoming HTTP requests, similar to @opentelemetry/instrumentation-koa, but is tailored for Fastify.
OpenTelemetry Koa Instrumentation for Node.js
![Apache License](https://img.shields.io/badge/license-Apache_2.0-green.svg?style=flat)
This module provides automatic instrumentation for the Koa module, which may be loaded using the @opentelemetry/sdk-trace-node
package and is included in the @opentelemetry/auto-instrumentations-node
bundle.
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+
.
Installation
npm install --save @opentelemetry/instrumentation-koa
Supported Versions
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 { NodeTracerProvider } = require('@opentelemetry/sdk-trace-node');
const { registerInstrumentations } = require('@opentelemetry/instrumentation');
const { KoaInstrumentation } = require('@opentelemetry/instrumentation-koa');
const provider = new NodeTracerProvider();
provider.register();
registerInstrumentations({
instrumentations: [
new KoaInstrumentation(),
],
});
See examples/koa
for a short example using both Koa and @koa/router
Koa Instrumentation Options
Options | Type | Example | Description |
---|
ignoreLayersType | KoaLayerType[] | ['middleware'] | Ignore layers of specified type. |
ignoreLayersType
accepts an array of KoaLayerType
which can take the following string values:
Koa Packages
This package provides automatic tracing for middleware added using either the core koa
package or the @koa/router
package.
Useful links
License
Apache 2.0 - See LICENSE for more information.