nestjs-otel/UPGRADING.md

NestJS OpenTelemetry Library

# Upgrading from v7 to v8

This guide provides instructions for upgrading `nestjs-otel` from version 7.x to version 8.x.

## Breaking Changes

### Metric Naming Convention

The default naming convention for metrics generated by decorators has changed to follow OpenTelemetry standards (using dots `.` instead of underscores `_` as separators).

**Previous Behavior (v7):**
- Instance Counter: `app_ClassName_instances_total`
- Method Counter: `app_ClassName_methodName_calls_total`

**New Behavior (v8):**
- Instance Counter: `app.ClassName.instances.total`
- Method Counter: `app.ClassName.methodName.calls.total`

**Action Required:**
If you are using default metric names in your dashboards (e.g., Grafana) or alerts, you will need to update the metric names to match the new dot-notation format.

If you were manually specifying names in the decorators (e.g., `@OtelMethodCounter({ name: 'my_custom_name' })`), no change is required as your custom names are preserved.

### Deprecated API Middleware and Configuration Removed

The deprecated API middleware and its associated configuration have been removed.

- The `apiMetrics` option in `OpenTelemetryModuleOptions` is no longer available.
- The `ApiMetricsMiddleware` class has been removed.

If you were relying on this middleware for request tracing, please ensure you are using the OpenTelemetry SDK's auto-instrumentation or the provided decorators.

## New Features

### New Decorators

v8 introduces several new decorators to improve the developer experience:

- **`@Traceable()`**: A class-level decorator that automatically applies tracing to all methods in a class.
  ```typescript
  @Traceable()
  @Injectable()
  export class MyService {
    // All methods are now traced automatically
  }
  ```

- **`@CurrentSpan()`**: A parameter decorator to inject the current OpenTelemetry Span into your controller methods.
  ```typescript
  @Get()
  findAll(@CurrentSpan() span: Span) {
    span.setAttribute('custom.attr', 'value');
  }
  ```

- **`@Baggage(key)`**: A parameter decorator to extract OpenTelemetry Baggage values.
  ```typescript
  @Get()
  findAll(@Baggage('tenant-id') tenantId: string) {
    // ...
  }
  ```

### Span Decorator Enhancements

The `@Span` decorator now supports capturing the return value of a method using the `onResult` callback.

```typescript
@Span({
  onResult: (result) => ({ attributes: { 'item.count': result.length } }),
})
async getItems() {
  return [1, 2, 3];
}
```