158 lines
4.4 KiB
Plaintext
158 lines
4.4 KiB
Plaintext
import { Prerequisites, TypeList } from "docs-ui"
|
|
|
|
export const metadata = {
|
|
title: `${pageNumber} Configure Instrumentation`,
|
|
}
|
|
|
|
# {metadata.title}
|
|
|
|
In this chapter, you'll learn about observability in Medusa and how to configure instrumentation with OpenTelemetry.
|
|
|
|
## Observability with OpenTelemtry
|
|
|
|
Medusa uses [OpenTelemetry](https://opentelemetry.io/) 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?
|
|
|
|
<Prerequisites
|
|
items={[
|
|
{
|
|
text: "An exporter to visualize your application's traces, such as Zipkin.",
|
|
link: "https://zipkin.io/pages/quickstart.html"
|
|
}
|
|
]}
|
|
/>
|
|
|
|
### Install Dependencies
|
|
|
|
Start by installing the following OpenTelemetry dependencies in your Medusa project:
|
|
|
|
```bash npm2yarn
|
|
npm install @opentelemetry/sdk-node @opentelemetry/resources @opentelemetry/sdk-trace-node @opentelemetry/instrumentation-pg
|
|
```
|
|
|
|
Also, install the dependencies relevant for the exporter you use. If you're using Zipkin, install the following dependencies:
|
|
|
|
```bash npm2yarn
|
|
npm install @opentelemetry/exporter-zipkin
|
|
```
|
|
|
|
### Add instrumentation.js
|
|
|
|
Next, create the file `instrumentation.js` with the following content:
|
|
|
|
```js title="instrumentation.js"
|
|
const { registerOtel } = require("@medusajs/medusa")
|
|
// If using an exporter other than Zipkin, require it here.
|
|
const { ZipkinExporter } = require("@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,
|
|
},
|
|
})
|
|
}
|
|
```
|
|
|
|
In the `instrumentation.js` 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:
|
|
|
|
<TypeList
|
|
types={[
|
|
{
|
|
name: "serviceName",
|
|
type: "`string`",
|
|
description: "The name of the service traced.",
|
|
optional: false
|
|
},
|
|
{
|
|
name: "exporter",
|
|
type: "[SpanExporter](https://open-telemetry.github.io/opentelemetry-js/interfaces/_opentelemetry_sdk_trace_base.SpanExporter.html)",
|
|
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: "instrumentations",
|
|
type: "[Instrumentation[]](https://open-telemetry.github.io/opentelemetry-js/interfaces/_opentelemetry_instrumentation.Instrumentation.html)",
|
|
description: "Additional instrumentation options that OpenTelemetry accepts.",
|
|
optional: true
|
|
}
|
|
]}
|
|
/>
|
|
|
|
---
|
|
|
|
## Test it Out
|
|
|
|
To test it out, start your exporter, such as Zipkin.
|
|
|
|
Then, start your Medusa application:
|
|
|
|
```bash npm2yarn
|
|
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
|
|
|
|
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 requests.
|
|
- `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.
|