NAME

Plack::Middleware::OpenTelemetry - Plack middleware to setup OpenTelemetry spans

VERSION

version 0.252280

SYNOPSIS

builder {
  enable "Plack::Middleware::OpenTelemetry",
    include_client_errors => 0;
};

# With custom resource attributes
builder {
  enable "Plack::Middleware::OpenTelemetry",
    include_client_errors => 1,
    resource_attributes => {
      'service.version' => '1.0.0',
      'deployment.environment' => 'production',
    };
};

DESCRIPTION

Plack::Middleware::OpenTelemetry will setup an OpenTelemetry span for the request.

The middleware automatically:

• Creates OpenTelemetry spans for HTTP requests

• Extracts W3C trace context from incoming requests

• Sets standard HTTP semantic attributes following OpenTelemetry conventions

• Handles both synchronous and streaming responses

• Records exceptions and sets appropriate span status

The following HTTP attributes are set on spans:

• http.request.method - HTTP method

• http.response.status_code - HTTP status code

• client.address - Client IP address

• server.address - Server hostname

• url.full - Full request URL

• url.scheme - URL scheme (http/https)

• url.path - URL path

• url.query - URL query string (if present)

• user_agent.original - User-Agent header

• http.response.body.size - Response body size

PARAMETERS

include_client_errors

By default client errors (HTTP status 400-499) don't set span status to "error". Enable this option to include them as errors.

resource_attributes

Hash reference of custom resource attributes to add to the OpenTelemetry resource. These will be merged with the default resource attributes.

Example: enable "Plack::Middleware::OpenTelemetry", resource_attributes => { 'service.version' => '1.0.0', 'deployment.environment' => 'production', };

ENVIRONMENT VARIABLES

The middleware respects standard OpenTelemetry environment variables:

OTEL_TRACES_EXPORTER

Exporter type (console, otlp, etc.)

OTEL_SERVICE_NAME

Service name for spans

OTEL_RESOURCE_ATTRIBUTES

Additional resource attributes

NOTES

The Net::Async::HTTP::Server plackup server is recommended: plackup -s Net::Async::HTTP::Server

SEE ALSO

Plack::Middleware, OpenTelemetry::SDK

AUTHOR

Ask Bjørn Hansen <ask@develooper.com>

COPYRIGHT AND LICENSE

This software is copyright (c) 2023 by Ask Bjørn Hansen.

This is free software; you can redistribute it and/or modify it under the MIT software license.