Koa Integration
Instrument Koa applications with one npm install. Middleware chain tracing, context propagation, error boundary support, and Node.js runtime metrics — zero configuration.
How It Works
Install the npm Package
Run npm install @tigerops/koa or yarn add @tigerops/koa. The package bundles @opentelemetry/instrumentation-koa with TigerOps OTLP exporters and a Node.js runtime metrics collector compatible with Koa 2.x and koa-router.
Use the TigerOps Middleware
Import { tigeropsMiddleware } from "@tigerops/koa" and app.use(tigeropsMiddleware()) as the very first middleware. The middleware creates root spans and patches ctx so that all downstream middleware share the active trace context.
Set Environment Variables
Set TIGEROPS_API_KEY, TIGEROPS_SERVICE_NAME, and TIGEROPS_ENVIRONMENT in your environment or .env file loaded via dotenv. The middleware reads these at startup before the first request arrives.
Traces, Context & Error Boundaries
Within seconds TigerOps receives Koa route spans, per-middleware execution times, error boundary catches with full stack traces, and outgoing HTTP client spans from your Koa application.
What You Get Out of the Box
Middleware Chain Tracing
Each Koa middleware function becomes a child span named after its function name or a provided label. The upstream and downstream execution phases (before and after next()) are measured separately, giving full visibility into onion-model timing.
Context Propagation
The active trace context is stored on ctx.tigerops so any middleware downstream can read the current span. W3C traceparent and tracestate headers are read from incoming requests and injected into outgoing HTTP calls automatically.
Error Boundary Support
Koa error events and ctx.throw() calls are caught and recorded as span exceptions with the error message, type, and stack trace. The span status is set to ERROR and the HTTP status code is recorded before the error propagates.
koa-router & @koa/router Support
Route patterns from koa-router and @koa/router are extracted and attached to spans as http.route. Named parameters in route paths are captured as span attributes without recording the raw matched value.
Node.js Runtime Metrics
Event loop lag, heap used, heap total, external memory, GC pause duration, and CPU usage are collected every 15 seconds via the Node.js perf_hooks and v8 APIs and exported as OTLP metrics.
Manual Span API via ctx
Access ctx.tigerops.startSpan("operation") from any middleware to create a custom child span. Spans support setAttribute, addEvent, and recordException. They are automatically ended when the returned span.end() is called or the middleware returns.
Install & Initialize
One npm install. One middleware use. Full Koa observability.
# Install the TigerOps Koa package
npm install @tigerops/koa
# Set environment variables
export TIGEROPS_API_KEY="your-api-key"
export TIGEROPS_SERVICE_NAME="my-koa-app"
export TIGEROPS_ENVIRONMENT="production"
// app.ts
import Koa from 'koa'
import Router from '@koa/router'
import bodyParser from '@koa/bodyparser'
import { tigeropsMiddleware } from '@tigerops/koa'
const app = new Koa()
app.proxy = true // trust X-Forwarded-* headers
// Register TigerOps FIRST
app.use(tigeropsMiddleware({
apiKey: process.env.TIGEROPS_API_KEY,
serviceName: process.env.TIGEROPS_SERVICE_NAME,
exclude: ['/health', '/metrics'],
slowMiddlewareThresholdMs: 50,
}))
app.use(bodyParser())
const router = new Router()
router.post('/orders', async (ctx) => {
// Add custom span attribute via ctx
ctx.tigerops.span?.setAttribute('order.items', ctx.request.body.items.length)
const order = await createOrder(ctx.request.body)
ctx.status = 201
ctx.body = order
})
app.use(router.routes())
app.listen(3000)Common Questions
Which Koa and Node.js versions are supported?
Koa 2.x is fully supported on Node.js 18, 20, and 22. Koa 1.x with generators is not supported. The middleware uses async/await and AsyncLocalStorage for trace context propagation across async middleware chains.
Does TigerOps work with koa-body or @koa/bodyparser?
Yes. Register tigeropsMiddleware before koa-body or @koa/bodyparser. The body parser adds a child span for body parsing time. TigerOps never captures the request body content — only the content-type and content-length are recorded.
How do I instrument a Koa app running behind a load balancer?
Set app.proxy = true in your Koa app configuration. TigerOps will read the real client IP from X-Forwarded-For and the real protocol from X-Forwarded-Proto and attach them to the root span.
Can I disable tracing for specific routes like /health?
Yes. Pass an exclude option to tigeropsMiddleware: tigeropsMiddleware({ exclude: ["/health", "/metrics"] }). Excluded routes do not create spans but their Node.js process metrics are still collected.
How does TigerOps handle Koa sessions and cookies?
TigerOps does not capture cookie values or session data. If you use koa-session or koa-jwt, the session ID (without content) can be recorded as a span attribute by calling ctx.tigerops.span?.setAttribute("session.id", ctx.session.id).
Full Koa Observability in One npm Install
Middleware chain traces, context propagation, error boundaries, and Node.js runtime metrics — no code changes required.