view release on metacpan or  search on metacpan

lib/Plack/Middleware/OpenTelemetry.pm  view on Meta::CPAN

        $span->record_exception($error)->set_attribute('http.response.status_code' => 500)
          ->set_status(SPAN_STATUS_ERROR, $message)->end;
        die $error;
    }
}

sub set_status_code ($self, $span, $res) {
    my $status_code = $res->[0] or return;
    $span->set_attribute("http.response.status_code", $status_code);
    if (   $status_code >= 400 and $self->include_client_errors
        or $status_code >= 500)
    {
        $span->set_status(SPAN_STATUS_ERROR);
    }
}

1;

=encoding utf8

=head1 NAME

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

=head1 VERSION

version 0.252280

=head1 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',
      };
  };

=head1 DESCRIPTION

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

The middleware automatically:

=over

=item * Creates OpenTelemetry spans for HTTP requests

=item * Extracts W3C trace context from incoming requests

=item * Sets standard HTTP semantic attributes following OpenTelemetry conventions

=item * Handles both synchronous and streaming responses

=item * Records exceptions and sets appropriate span status

=back

The following HTTP attributes are set on spans:

=over

=item * C<http.request.method> - HTTP method

=item * C<http.response.status_code> - HTTP status code

=item * C<client.address> - Client IP address

=item * C<server.address> - Server hostname

=item * C<url.full> - Full request URL

=item * C<url.scheme> - URL scheme (http/https)

=item * C<url.path> - URL path

=item * C<url.query> - URL query string (if present)

=item * C<user_agent.original> - User-Agent header

=item * C<http.response.body.size> - Response body size

=back

=head1 PARAMETERS

=over

=item 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.

=item 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',
    };

=back

=head1 ENVIRONMENT VARIABLES

The middleware respects standard OpenTelemetry environment variables:

=over