view release on metacpan or  search on metacpan

lib/Mojolicious/Plugin/OpenTelemetry.pod  view on Meta::CPAN

            tracer => \%tracer_args,
        },
    );

Registers this plugin in a L<Mojolicious> application.

When registered, this plugin will install a wrapper around any endpoint
action (as described in L<Mojolicious/around_action>). Actions that are not
endpoints will be unaffected.

Before the action is executed, a
L<server|OpenTelemetry::Constants/SPAN_KIND_SERVER>
L<span|OpenTelemetry::Tracer::Span> will be created and injected into the
current L<context|OpenTelemetry::Context>, together with any propagation data
retrieved from the incoming request headers by the currently installed
L<propagator|OpenTelemetry/propagator>.

The value of the C<tracer> parameter passed on registration will be used to
obtain a L<tracer|OpenTelemetry::Trace::Tracer> via
L<OpenTelemetry::Trace::TracerProvider/tracer>. Setting this is optional. If
no value is set, the value will be read from the
L<"OTEL_SERVICE_NAME"|OpenTelemetry::SDK/OTEL_SERVICE_NAME> environment
variable, or from the app's L<moniker|Mojolicious/moniker>, will be used as
the default name, but all other values will be left unspecified.

Due to constraints in the L<Mojolicious> dispatch logic, the span will be created
with a generic name made up of only the method of the request. This name will
later be extended to include the stringified
L<endpoint|Mojolicious::Routes::Match/endpoint> of the matching route, as in
C<GET /foo/:bar>, to reduce the span cardinality. Note that this means that
any L<sampling decisions|OpenTelemetry::SDK::Trace::Sampler> I<will only see this
temporary generic name>.

Samplers will also have access to the following attributes, which will be set
at the time of span creation:

=over

=item C<http.request.method>

Set to the L<request method|Mojo::Message::Request/method>. It will be the
same value that was concatenated to the route in the span's name.

=item C<network.protocol.version>

Set to the L<request version|Mojo::Message::Request/version>.

=item C<url.path>

Set to the path of the request URL. This will be the raw path, without using
any placeholders. It will not include the query string.

=item C<url.scheme>

Set to the scheme of the request URL.

=item C<client.address>

Set to the
L<remote address of the transaction|Mojo::Transaction/remote_address>. This
will respect the value set in the C<X-Forwarded-For> header, if any.

=item C<client.port>

Set to the L<remote port of the transaction|Mojo::Transaction/remote_port>.

=item C<server.address>

Set to the host portion of the C<host> value in the leftmost entry in the
C<Forwarded> header, falling back to the value of the C<X-Forwarded-Proto>
header, or to the value of the C<Host> header if no other is set. The host
portion is the part before an optional port number.

See the
L<semantic conventions entry for this attribute|https://opentelemetry.io/docs/specs/semconv/http/http-spans/#setting-serveraddress-and-serverport-attributes>
for more details on this logic.

If no value could be determined, this attribute will not be present.

=item C<server.port>

Set to the port number in the C<host> value in the leftmost entry in the
C<Forwarded> header, falling back to the value of the C<X-Forwarded-Proto>
header, or to the value of the C<Host> header if no other is set.

See the
L<semantic conventions entry for this attribute|https://opentelemetry.io/docs/specs/semconv/http/http-spans/#setting-serveraddress-and-serverport-attributes>
for more details on this logic.

The port number in these is optional. If none is set, or none could be
determined, this attribute will not be present.

=item C<user_agent.original>

Set to the value of the L<user agent header|Mojo::Headers/user_agent>. If not
set, this attribute will not be present.

=item C<url.query>

Set to the L<query of the request URL|Mojo::URL/query>, if present. If the URL
had no query parameters, this attribute will not be present.

=back

The attributes described below will be set in the span once the transaction is
completed, but will not be available for the sampler.

=over

=item C<error.type>

If an error is encountered during the execution of the action, this attribute
will be set to the package name of the error (as reported by
L<"ref"|https://perldoc.perl.org/functions/ref>), or the value C<string> if
the error is not blessed into any package.

If there were no errors, this attribute will not be present.

=item C<http.response.status_code>

Set to the L<status code of the response|Mojo::Message::Response/code>. If an