- Get Started
- Product
- Resources
- Tools & SDKs
- Framework
- Reference
- Get Started
- Product
- Resources
- Tools & SDKs
- Framework
- Reference
7.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:
Also, install the dependencies relevant for the exporter you use. If you're using Zipkin, install the following dependencies:
Add instrumentation.ts#
Next, create the file instrumentation.ts
with the following content:
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.
The registerOtel
utility function accepts an object having the following properties:
serviceName
stringexporter
SpanExporterinstrument
objectOptionalOptions specifying what to trace.
instrument
objectOptionalTest it Out#
To test it out, start your exporter, such as Zipkin.
Then, start your Medusa application:
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.