
=head1 NAME

OpenTracing::Implementation::DataDog - Sending traces to DataDog using Agent



=head1 VERSION

This is version 'v0.47.1'



=head1 WARNING

This version is for

=over

=item L<OpenTracing::Interface> version B<v0.204.x>

=item L<OpenTracing::Role> vesion B<v0.81.2>

=back



=head1 SYNOPSIS

    use aliased "OpenTracing::Implementation::DataDog", 'Implementation';
    
    my $tracer = Implementation->bootstrap_tracer(
        agent => {
            host            => 'localhost',
            port            => '8126',
            path            => 'v0.3/traces',
        },
        default_service_name    => 'MyService',
        default_service_type    => 'web',
        default_resource_name   => 'my_cgi_endpoint',
        default_hostname        => 'my.host.123',
        default_environment     => 'staging',
    );



=head1 DESCRIPTION

This `DataDog` implementation for 'OpenTracing' is fully compliant with the open
source definition of L<OpenTracing::Interface>. 

This implementation connects to the C<localhost> installed agent by default,
that listens to port C<8126>. It recieves traces at the C</v0.3/traces>
endpoint.



=head1 CLASS METHODS



=head2 bootstrap_tracer

    my $tracer = OpenTracing::Implementation::DataDog->bootstrap_tracer( );

Returns a L<OpenTracing::Interface::Tracer> compliant tracer, using the
L<OpenTracing::Implementation::NoOp::Tracer> implementation.

=head3 named paramters

=over

=item agent

A hasreference with instantiation options for
L<OpenTracing::Implementation::DataDog::Client>.

=item default_context

A hasreference with instantiation options for
L<OpenTracing::Implementation::DataDog::SpanContext>. This will be used if no
context can be found for C<<$tracer->extract_context>>.

=back



=head1 ENVIRONMENT VARIABLES

For configuring DataDog Tracing there is support for the folllowing environment
variables:



=head2 C<DD_AGENT_HOST>

Hostname for where to send traces to. If using a containerized environment,
configure this to be the host IP.

B<default:> C<localhost>



=head2 C<DD_TRACE_AGENT_PORT>

The port number the Agent is listening on for configured host. If the Agent
configuration sets receiver_port or C<DD_APM_RECEIVER_PORT> to something other
than the default B<8126>, then C<DD_TRACE_AGENT_PORT> or C<DD_TRACE_AGENT_URL>
must match it.

B<default:> C<8126>


=head2 C<DD_TRACE_AGENT_URL>

The URL to send traces to. If the Agent configuration sets receiver_port or
C<DD_APM_RECEIVER_PORT> to something other than the default B<8126>, then
C<DD_TRACE_AGENT_PORT> or C<DD_TRACE_AGENT_URL> must match it. The URL value can
start with C<http://> to connect B<using HTTP> or with C<unix://> to use a
B<Unix Domain Socket>.

When set this takes precedence over C<DD_AGENT_HOST> and C<DD_TRACE_AGENT_PORT>.

B<CAVEATE: > the C<unix:> scheme is non-exisitent, and is not supported with the
L<DataDog::Client|OpenTracing::Implementation::DataDog::Client>.



=head2 C<DD_TRACE_PARTIAL_FLUSH_MIN_SPANS>

Set a number of partial spans to flush on. Useful to reduce memory overhead when
dealing with heavy traffic or long running traces.

B<default:> 100



=head2 C<DD_SERVICE_NAME>

The name of a set of processes that do the same job. Used for grouping stats for
your application.

B<default:> I<none>



=head2 C<DD_ENV>

Your application environment (for example, production, staging).

B<default:> I<none>



=head2 C<DD_HOSTNAME>

Manually set the hostname to use for metrics if autodetection fails, or when
running the Datadog Cluster Agent.



=head2 C<DD_VERSION>

Your application version (for example, 2.5, 202003181415, 1.3-alpha).

B<default:> I<none>


=head2 C<DD_TRACE_PROPAGATION_STYLE>

Comma separated list of propagation styles used for extracting trace context from inbound request headers and injecting trace context into outbound request headers.

Overridden by C<DD_TRACE_PROPAGATION_STYLE_EXTRACT> for extraction.

Overridden by C<DD_TRACE_PROPAGATION_STYLE_INJECT> for injection.

The supported values are:

=over

=item datadog

DataDog native headers, C<x-datadog-trace-id> and C<x-datadog-parent-id>.

=item b3multi

L<https://github.com/openzipkin/b3-propagation#multiple-headers>

=item b3 single header

L<https://github.com/openzipkin/b3-propagation#single-header>

=item tracecontext

L<https://www.w3.org/TR/trace-context/>

=item none

Propagation disabled.

=back

When checking inbound request headers we will take the first valid trace context
in the order provided.

When C<none> is the only propagator listed, propagation is disabled.

All provided styles are injected into the headers of outbound requests.

Example: C<DD_TRACE_PROPAGATION_STYLE="datadog,b3multi"> to check for both
C<x-datadog-*> and C<x-b3-*> headers when parsing incoming request headers
for a trace context. In addition, to inject both C<x-datadog-*>
and C<x-b3-*> headers into outbound requests.

B<default:> datadog


=head2 C<DD_TRACE_PROPAGATION_STYLE_EXTRACT>

Override the propagation style for extraction only, see L<DD_TRACE_PROPAGATION_STYLE> for supported values.


=head2 C<DD_TRACE_PROPAGATION_STYLE_INJECT>

Override the propagation style for injection only, see L<DD_TRACE_PROPAGATION_STYLE> for supported values.


=head2 STRICT

STRICT on itself not a environment variable, but a boolean constant from
L<Devel::StrictMode> that uses the following set of environment variables:

=head2 C<PERL_STRICT>

=head2 C<EXTENDED_TESTING>

=head2 C<AUTHOR_TESTING>

=head2 C<RELEASE_TESTING>

When any of those are set, tests are run using type constraints and parameter
checks are performed, as well as return objects or values. During production it
is recommended to keep these switched off for performance improvements.



=head1 AUTHOR

Theo van Hoesel <tvanhoesel@perceptyx.com>



=head1 COPYRIGHT AND LICENSE

'OpenTracing::Implementation::DataDog'
is Copyright (C) 2019 .. 2021, Perceptyx Inc

This library is free software; you can redistribute it and/or modify it under
the terms of the Artistic License 2.0.

This package is distributed in the hope that it will be useful, but it is
provided "as is" and without any express or implied warranties.

For details, see the full text of the license in the file LICENSE.


=cut
