www/apps/book/app/learn/debugging-and-testing/instrumentation/page.mdx
import { Prerequisites, TypeList } from "docs-ui"
export const metadata = {
title: ${pageNumber} Configure Instrumentation,
}
In this chapter, you'll learn about observability in Medusa and how to configure instrumentation with OpenTelemetry.
Instrumentation is the collection of data about your application's performance and errors. It helps you debug issues, monitor performance, and gain insights into how your application behaves in production.
Instrumentation and observability are crucial as you build customizations in your application. They allow you to optimize performance, identify bottlenecks, and ensure your application runs smoothly.
Medusa uses OpenTelemetry for instrumentation and reporting. When configured, it reports traces for:
<Prerequisites items={[ { text: "An exporter to visualize your application's traces, such as Zipkin.", link: "https://zipkin.io/pages/quickstart.html" } ]} />
As of Medusa v2.11.0, OpenTelemetry dependencies are installed by default in new Medusa projects. If you're using an older version of Medusa, you need to install the @opentelemetry/sdk-node, @opentelemetry/resources, @opentelemetry/sdk-trace-node, and @opentelemetry/instrumentation-pg dependencies.
Before you start, you must install the dependencies relevant for the exporter you use. If you're using Zipkin, install the following dependencies:
npm install @opentelemetry/exporter-zipkin
Next, create the file instrumentation.ts with the following content:
import { registerOtel } from "@medusajs/medusa"
import { ZipkinExporter } from "@opentelemetry/exporter-zipkin"
// If using an exporter other than Zipkin, initialize it here.
const exporter = new ZipkinExporter({
serviceName: "my-medusa-project",
})
export function register() {
registerOtel({
serviceName: "medusajs",
// pass exporter
exporter,
instrument: {
http: true,
workflows: true,
query: true,
db: true,
cache: true,
},
})
}
In the instrumentation.ts file, you export a register function that uses Medusa's registerOtel utility function. You also initialize an instance of the exporter, such as Zipkin, and pass it to the registerOtel function.
registerOtel accepts an object where you can pass any NodeSDKConfiguration property along with the following properties:
The NodeSDKConfiguration properties are accepted since Medusa v2.5.1.
<TypeList
types={[
{
name: "serviceName",
type: "string",
description: "The name of the service traced.",
optional: false
},
{
name: "exporter",
type: "SpanExporter",
description: "An instance of an exporter, such as Zipkin."
},
{
name: "instrument",
type: "object",
description: "Options specifying what to trace.",
optional: true,
children: [
{
name: "http",
type: "boolean",
description: "Whether to trace HTTP requests."
},
{
name: "query",
type: "boolean",
description: "Whether to trace Query usages."
},
{
name: "workflows",
type: "boolean",
description: "Whether to trace Workflow executions."
},
{
name: "db",
type: "boolean",
description: "Whether to trace database queries and operations."
},
{
name: "cache",
type: "boolean",
description: "Whether to trace cache operations."
},
]
},
{
name: "instrumentations",
type: "Instrumentation[]",
description: "Additional instrumentation options that OpenTelemetry accepts.",
optional: true
}
]}
/>
To test it out, start your exporter, such as Zipkin.
Then, start your Medusa application:
npm run dev
Try to open the Medusa Admin or send a request to an API route.
If you check traces in your exporter, you'll find new traces reported.
Trace span names start with the following keywords based on what it's reporting:
{methodName} {URL} when reporting HTTP requests, where {methodName} is the HTTP method, and {URL} is the URL the request is sent to.route: when reporting route handlers running on an HTTP request.middleware: when reporting a middleware running on an HTTP request.workflow: when reporting a workflow execution.step: when reporting a step in a workflow execution.query.graph: when reporting Query usages.pg.query: when reporting database queries and operations.