5.4. Configure Instrumentation

In this chapter, you'll learn about observability in Medusa and how to configure instrumentation with OpenTelemetry.

Observability with OpenTelemtry#

Medusa uses OpenTelemetry for instrumentation and reporting. When configured, it reports traces for:

• HTTP requests
• Workflow executions
• Query usages
• Database queries and operations

How to Configure Instrumentation in Medusa?#

Install Dependencies#

Start by installing the following OpenTelemetry dependencies in your Medusa project:

npm
yarn
pnpm

Also, install the dependencies relevant for the exporter you use. If you're using Zipkin, install the following dependencies:

npm
yarn
pnpm

Add instrumentation.ts#

Next, create the file instrumentation.ts with the following content:

instrumentation.ts
1import { registerOtel } from "@medusajs/medusa"2import { ZipkinExporter } from "@opentelemetry/exporter-zipkin"3
4// If using an exporter other than Zipkin, initialize it here.5const exporter = new ZipkinExporter({6  serviceName: "my-medusa-project",7})8
9export function register() {10  registerOtel({11    serviceName: "medusajs",12    // pass exporter13    exporter,14    instrument: {15      http: true,16      workflows: true,17      query: true,18    },19  })20}

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 having the following properties:

Test it Out#

To test it out, start your exporter, such as Zipkin.

Then, start your Medusa application:

npm
yarn
pnpm

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#

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.