https://github.com/platformatic/instrumentation-light-my-request
OpenTelemetry instrumentation for light-my-request
https://github.com/platformatic/instrumentation-light-my-request
Last synced: 2 months ago
JSON representation
OpenTelemetry instrumentation for light-my-request
- Host: GitHub
- URL: https://github.com/platformatic/instrumentation-light-my-request
- Owner: platformatic
- License: mit
- Created: 2025-12-29T13:46:18.000Z (3 months ago)
- Default Branch: main
- Last Pushed: 2026-01-09T11:25:48.000Z (2 months ago)
- Last Synced: 2026-01-12T17:13:16.684Z (2 months ago)
- Language: JavaScript
- Size: 49.8 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
- Notice: NOTICE
Awesome Lists containing this project
README
# @platformatic/instrumentation-light-my-request
OpenTelemetry instrumentation for `light-my-request`, which instruments Fastify's `inject()` method for testing and internal request handling.
## Installation
```bash
npm install @platformatic/instrumentation-light-my-request
```
## Usage
This instrumentation automatically patches `light-my-request` to create OpenTelemetry spans for injected requests. This is useful because `fastify.inject()` bypasses HTTP entirely, so standard HTTP instrumentation doesn't capture these operations.
### With NodeSDK
```javascript
import { NodeSDK } from '@opentelemetry/sdk-node'
import { LightMyRequestInstrumentation } from '@platformatic/instrumentation-light-my-request'
const sdk = new NodeSDK({
instrumentations: [
new LightMyRequestInstrumentation()
]
})
sdk.start()
```
### With registerInstrumentations
```javascript
import { registerInstrumentations } from '@opentelemetry/instrumentation'
import { LightMyRequestInstrumentation } from '@platformatic/instrumentation-light-my-request'
registerInstrumentations({
instrumentations: [
new LightMyRequestInstrumentation()
]
})
```
## Features
- **Automatic span creation**: Creates SERVER spans for each `inject()` call
- **Context propagation**: Extracts trace context from injected headers
- **Error tracking**: Records exceptions and sets appropriate span status
- **Promise and callback support**: Works with both callback and promise-based inject calls
- **Provider-agnostic**: Uses `this.tracer` getter, works with any TracerProvider
## Span Attributes
This instrumentation follows OpenTelemetry semantic conventions and sets the following attributes:
### Required Attributes
- `http.request.method`: HTTP method (GET, POST, etc.)
- `url.path`: Path portion of the URL (without query string)
- `url.scheme`: URL scheme (defaults to "http")
### Recommended Attributes
- `url.full`: Full URL of the request
- `server.address`: Server hostname (extracted from Host header)
- `server.port`: Server port (extracted from Host header)
- `client.address`: Client IP address (from `remoteAddress` option)
- `user_agent.original`: User-Agent header value
- `network.protocol.version`: HTTP protocol version (if available)
### Conditionally Required Attributes
- `http.response.status_code`: HTTP status code (set when response is received)
- `url.query`: Query string portion of the URL (set when query parameters are present)
- `error.type`: Error type/name for exceptions, or HTTP status code for 4xx/5xx responses
## Why This Instrumentation?
Fastify's `inject()` method is used for:
- Testing Fastify applications
- Internal request routing (e.g., in Platformatic's thread-interceptor)
- Simulating HTTP requests without network overhead
Since these requests bypass HTTP, standard HTTP instrumentation doesn't see them. This instrumentation fills that gap by patching `light-my-request` directly.
## Compatibility
- **light-my-request**: >=4.0.0
- **Node.js**: >=20.0.0
- **@opentelemetry/api**: ^1.0.0
- Works with any OpenTelemetry-compatible TracerProvider
## License
Apache-2.0