NAME

OpenTracing::Implementation::DataDog::Client - A Client that sends off the spans

SYNOPSIS

    use alias OpenTracing::Implementation::DataDog::Client;
    
    my $datadog_client = ->new(
        http_user_agent => LWP::UserAgent->new();
        host            => 'localhost',
        port            => '8126',
        path            => 'v0.3/traces',
    ); # these are defaults

and later:

    $datadog_client->send_span( $span );

DESCRIPTION

The main responsabillity of this Client is to provide the send_span method, that will send the data to the local running DataDog agent.

It does this by calling to_struct that massages the generic OpenTracing data, like baggage_items from SpanContext and tags from Span, together with the DataDog specific data like resource_name.

This structure will be send of as a JSON string to the local installed DataDog agent.

OPTIONAL ATTRIBUTES

The attributes below can be set during instantiation, but none are required and have sensible defaults, that may actually play nice with known DataDog environment variables

http_user_agent

A HTTP User Agent that connects to the locally running DataDog agent. This will default to a LWP::UserAgent, but any User Agent will suffice, as long as it has a required delegate method request, that takes a HTTP::Request object and returns a HTTP::Response compliant response object.

scheme

The scheme being used, should be either http or https, defaults to http

host

The host-name where the DataDog agent is running, which defaults to localhost or the value of DD_AGENT_HOST environment variable if set.

port

The port-number the DataDog agent is listening at, which defaults to 8126 or the value of the DD_TRACE_AGENT_PORT environment variable if set.

path

The path the DataDog agent is expecting requests to come in, which defaults to v0.3/traces.

agent_url

The complete URL the DataDog agent is listening at, and defaults to the value of the DD_TRACE_AGENT_URL environment variable if set. If this is set, it takes precedence over any of the other settings.

NOTE: DataDog Agents can also listen to a UNiX socket, and one is suggested that there is a unix: URL. Fist of all, that is false, the unix: scheme is just non existent. It should be file: instead. Secondly, this Client just does not support it, only http: or https:

span_buffer_threshold

This sets the size limit of the span buffer. When this number is reached, this Client will send off the buffered spans using the internal user_agent.

This number can be set on instantiation, or will take it from the DD_TRACE_PARTIAL_FLUSH_MIN_SPANS environment variable. If nothing is set, it defaults to 100.

The number can not be set to anything higher than 20_000.

If this number is 0 (zero), spans will be sent with each call to send_span.

DELEGATED INSTANCE METHODS

The following method(s) are required by the DataDog::Tracer:

send_span

This method gets called by the DataDog::Tracer to send a Span with its specific DataDog::SpanContext.

This will typically get called during on_finish.

Required Positional Arguments

$span

An OpenTracing Span compliant object, that will be serialised (using to_struct and converted to JSON).

Returns

undef

in case something went wrong during the HTTP-request or the client has been halted in any previous call.

a positive int

indicating the number of collected spans, in case this client has only buffered the span.

a negative int

indicating the number of flushed spans, in case the client has succesfully flushed the spans collected in the buffer.

INSTANCE METHODS

to_struct

Gather required data from a single span and its context, tags and baggage items.

Required Positional Arguments

$span

Returns

a hashreference with the following keys:

trace_id

span_id

resource

service

type (optional)

env (optional)

hostname (optional)

name

start

duration

parent_id (optional)

error

meta (optional)

metrics

Notes

This data structure is specific for sending it through the DataDog agent and therefore can not be a intance method of the DataDog::Span object.

ENVIRONMENT VARIABLES

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

DD_AGENT_HOST

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

default: localhost

DD_TRACE_AGENT_PORT

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

default: 8126

DD_TRACE_AGENT_URL

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

When set this takes precedence over DD_AGENT_HOST and DD_TRACE_AGENT_PORT.

CAVEATE: the unix: scheme is non-exisitent, and is not supported with the DataDog::Client.

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.

default: 100

SEE ALSO

OpenTracing::Implementation::DataDog

Sending traces to DataDog using Agent.

DataDog Docs API Tracing

The DataDog Agent API Documentation.

LWP::UserAgent

Web user agent class

JSON::Maybe::XS

Use Cpanel::JSON::XS with a fallback to JSON::XS and JSON::PP

HTTP::Request

HTTP style request message

HTTP::Response

HTTP style response message

AUTHOR

Theo van Hoesel <tvanhoesel@perceptyx.com>

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.

cpanm OpenTracing::Implementation::DataDog

perl -MCPAN -e shell
install OpenTracing::Implementation::DataDog