File Coverage

blib/lib/OpenTracing/Implementation/DataDog/SpanContext.pm
Criterion Covered Total %
statement 30 30 100.0
branch n/a
condition n/a
subroutine 14 14 100.0
pod 6 6 100.0
total 50 50 100.0


line stmt bran cond sub pod time code
1             package OpenTracing::Implementation::DataDog::SpanContext;
2              
3             =head1 NAME
4              
5             OpenTracing::Implementation::DataDog::SpanContext - A DataDog Implementation
6              
7             =cut
8              
9             our $VERSION = 'v0.46.2';
10              
11              
12             =head1 SYNOPSIS
13              
14             use aliased OpenTracing::Implementation::DataDog::SpanContext;
15            
16             my $span_context = SpanContext->new(
17             service_name => "MyFancyService",
18             service_type => "web",
19             resource_name => "/clients/{client_id}/contactdetails",
20             environment => 'staging',
21             hostname => 'web.01.host',
22             );
23             #
24             # please do not add parameter values in the resource,
25             # use tags instead, like:
26             # $span->set_tag( client_id => $request->query_params('client_id') )
27              
28             =cut
29              
30 26     26   1996199 use Moo;
  26         74744  
  26         155  
31 26     26   35762 use MooX::Enumeration; # do needs to be the first eXtension
  26         68058  
  26         142  
32 26     26   11548 use MooX::Attribute::ENV;
  26         115966  
  26         270  
33 26     26   10848 use MooX::Should;
  26         40308  
  26         174  
34              
35             with 'OpenTracing::Role::SpanContext';
36              
37 26     26   10257 use OpenTracing::Implementation::DataDog::Utils qw/random_bigint/;
  26         118  
  26         1815  
38              
39 26     26   12790 use Sub::Trigger::Lock;
  26         100047  
  26         348  
40 26     26   21559 use Types::Common::String qw/NonEmptyStr/;
  26         2942608  
  26         256  
41 26     26   29381 use Types::Standard qw/InstanceOf Maybe/;
  26         78  
  26         184  
42              
43              
44              
45             =head1 DESCRIPTION
46              
47             This is a L<OpenTracing SpanContext|OpenTracing::Interface::SpanContext>
48             compliant implementation with DataDog specific extentions
49              
50             =cut
51              
52              
53              
54             =head1 EXTENDED ATTRIBUTES
55              
56             =cut
57              
58              
59              
60             =head2 C<trace_id>
61              
62             DataDog requires this to be a unsigned 64-bit integer
63              
64             =cut
65              
66             has '+trace_id' => (
67             is =>'ro',
68             should => InstanceOf['Math::BigInt'],
69             default => sub{ random_bigint() }
70             );
71              
72              
73              
74             =head2 C<span_id>
75              
76             DataDog requires this to be a unsigned 64-bit integer
77              
78             =cut
79              
80             has '+span_id' => (
81             is =>'ro',
82             should => InstanceOf['Math::BigInt'],
83             default => sub{ random_bigint() }
84             );
85              
86              
87              
88             =head1 DATADOG SPECIFIC ATTRIBUTES
89              
90             =cut
91              
92              
93              
94             =head2 C<service_name>
95              
96             A required C<NonEmptyString> where C<length <= 100>.
97              
98             Defaults to the value of the C<DD_SERVICE_NAME> environment variable if set.
99              
100             The service-name will usually be the name of the application and could easilly
101             be set by a intergration solution.
102              
103             =cut
104              
105             has service_name => (
106             is => 'ro',
107             env_key => [ 'DD_SERVICE', 'DD_SERVICE_NAME' ], # only DD_SERVICE!!
108             required => 1,
109             should => NonEmptyStr->where( 'length($_) <= 100' ),
110             reader => 'get_service_name',
111             trigger => Lock,
112             );
113              
114              
115              
116             =head2 C<service_type>
117              
118             An enumeration on C<web>, C<db>, C<cache>, and C<custom>, which is the default.
119              
120             DataDog has four different service types to make it more easy to visualize the
121             data. See L<Service List at DataDog HQ|
122             https://docs.datadoghq.com/tracing/visualization/services_list/#services-types>
123              
124             =cut
125              
126             has service_type => (
127             is => 'ro',
128             default => 'custom',
129             enum => [qw/web db cache custom/],
130             handles => 2, # such that we have `service_type_is_...`
131             reader => 'get_service_type',
132             trigger => Lock,
133             );
134              
135              
136              
137             =head2 C<resource_name>
138              
139             A required C<NonEmptyString> where C<length <= 5000>.
140              
141             Good candidates for resource names are URL paths or databasenames and or tables.
142              
143             =cut
144              
145             has resource_name => (
146             is => 'ro',
147             should => NonEmptyStr->where( 'length($_) <= 5000' ),
148             required => 1,
149             reader => 'get_resource_name',
150             trigger => Lock,
151             );
152              
153              
154              
155             =head2 C<environment>
156              
157             An optional C<NonEmptyString> where C<length <= 5000>.
158              
159             =cut
160              
161             has environment => (
162             is => 'ro',
163             should => Maybe[NonEmptyStr->where( 'length($_) <= 5000' )],
164             required => 0,
165             env_key => 'DD_ENV',
166             reader => 'get_environment',
167             trigger => Lock,
168             );
169              
170              
171              
172             =head2 C<hostname>
173              
174             An optional C<NonEmptyString> where C<length <= 5000>.
175              
176             =cut
177              
178             has hostname => (
179             is => 'ro',
180             should => Maybe[NonEmptyStr->where( 'length($_) <= 5000' )],
181             required => 0,
182             env_key => 'DD_HOSTNAME',
183             reader => 'get_hostname',
184             trigger => Lock,
185             );
186              
187              
188              
189             =head2 C<version>
190              
191             An optional C<NonEmptyString> where C<length <= 5000>.
192              
193             =cut
194              
195             has version => (
196             is => 'ro',
197             should => Maybe[NonEmptyStr->where( 'length($_) <= 5000' )],
198             required => 0,
199             env_key => 'DD_VERSION',
200             reader => 'get_version',
201             trigger => Lock,
202             );
203              
204              
205              
206             =head1 CONSTRUCTORS
207              
208             =head2 Warning:
209              
210             Constructors are not to be used outside an implementation, they are not part of
211             the L<OpenTracing API|OpenTracing::Interface>.
212              
213             Only an integration solution should be bothered creating a 'root context'.
214              
215             =head2 new
216              
217             my $span_context = SpanContext->new(
218             service_name => "MyFancyService",
219             resource_name => "/clients/{client_id}/contactdetails",
220             baggage_items => { $key => $value, .. },
221             );
222              
223             Creates a new SpanContext object;
224              
225              
226              
227             =head1 INSTANCE METHODS
228              
229             Besides all methods available from the L<OpenTracing::Roles::SpanContext>, the
230             following are DataDog specific added methods.
231              
232             =cut
233              
234              
235              
236             =head2 C<service_type_is_web>
237              
238             Returns a C<Bool> wether or not the L<service_type> is set to C<web>.
239              
240             =head2 C<service_type_is_db>
241              
242             Returns a C<Bool> wether or not the L<service_type> is set to C<db>.
243              
244             =head2 C<service_type_is_cache>
245              
246             Returns a C<Bool> wether or not the L<service_type> is set to C<cache>.
247              
248             =head2 C<service_type_is_ciustom>
249              
250             Returns a C<Bool> wether or not the L<service_type> is set to C<custom>.
251              
252             =cut
253              
254              
255              
256             =head1 CLONE METHODS
257              
258             Since C<SpanContext> is supposed to be an in-mutable object, and there are some
259             occasions that DataDog settings need to added (i.e. a root span), there are a
260             few cloning methods provided:
261              
262             =cut
263              
264              
265              
266             =head2 C<with_service_name>
267              
268             Creates a cloned object, with a new value for C<service_name>.
269              
270             $span_context_new = $root_span->with_service_name( 'MyAwesomeApp' );
271              
272             =head3 Required Positional Parameter(s)
273              
274             =over
275              
276             =item C<service_name>
277              
278             A C<NonEmptyString> where C<length <= 100>.
279              
280             =back
281              
282             =head3 Returns
283              
284             A cloned C<DataDog::SpanContext>
285              
286             =cut
287              
288 1     1 1 1208 sub with_service_name { $_[0]->clone_with( service_name => $_[1] ) }
289              
290              
291              
292             =head2 C<with_service_type>
293              
294             Creates a cloned object, with a new value for C<service_type>.
295              
296             $span_context_new = $root_span->with_service_type( 'cache' );
297              
298             =head3 Required Positional Parameter(s)
299              
300             =over
301              
302             =item C<service_type>
303              
304             An enumeration on C<web>, C<db>, C<cache>, and C<custom>
305              
306             =back
307              
308             =head3 Returns
309              
310             A cloned C<DataDog::SpanContext>
311              
312             =cut
313              
314 1     1 1 1098 sub with_service_type { $_[0]->clone_with( service_type => $_[1] ) }
315              
316              
317              
318             =head2 C<with_resource_name>
319              
320             Creates a cloned object, with a new value for C<resource_name>.
321              
322             $span_context_new = $root_span->with_resource_name( 'clients/?/index.cgi' );
323              
324             =head3 Required Positional Parameter(s)
325              
326             =over
327              
328             =item C<resource_name>
329              
330             A C<NonEmptyString> where C<length <= 5000>.
331              
332             =back
333              
334             =head3 Returns
335              
336             A cloned C<DataDog::SpanContext>
337              
338             =cut
339              
340 1     1 1 1300 sub with_resource_name { $_[0]->clone_with( resource_name => $_[1] ) }
341              
342              
343              
344             =head2 C<with_environment>
345              
346             Creates a cloned object, with a new value for C<environment>.
347              
348             $span_context_new = $root_span->with_environment( 'development' );
349              
350             =head3 Required Positional Parameter(s)
351              
352             =over
353              
354             =item C<environment>
355              
356             A C<NonEmptyString> where C<length <= 5000>.
357              
358             =back
359              
360             =head3 Returns
361              
362             A cloned C<DataDog::SpanContext>
363              
364             =cut
365              
366 1     1 1 1200 sub with_environment { $_[0]->clone_with( environment => $_[1] ) }
367              
368              
369              
370             =head2 C<with_hostname>
371              
372             Creates a cloned object, with a new value for C<hostname>.
373              
374             $span_context_new = $root_span->with_hostname( 'web.01.host' );
375              
376             =head3 Required Positional Parameter(s)
377              
378             =over
379              
380             =item C<hostname>
381              
382             A C<NonEmptyString> where C<length <= 5000>.
383              
384             =back
385              
386             =head3 Returns
387              
388             A cloned C<DataDog::SpanContext>
389              
390             =cut
391              
392 1     1 1 1242 sub with_hostname { $_[0]->clone_with( hostname => $_[1] ) }
393              
394              
395              
396             =head2 C<with_version>
397              
398             Creates a cloned object, with a new value for C<hostname>.
399              
400             $span_context_new = $root_span->with_version( 'v0.123.456' );
401              
402             =head3 Required Positional Parameter(s)
403              
404             =over
405              
406             =item C<version>
407              
408             A C<NonEmptyString> where C<length <= 5000>.
409              
410             =back
411              
412             =head3 Returns
413              
414             A cloned C<DataDog::SpanContext>
415              
416             =cut
417              
418 1     1 1 1323 sub with_version { $_[0]->clone_with( version => $_[1] ) }
419              
420              
421              
422             =head1 ENVIRONMENT VARIABLES
423              
424             For configuring DataDog Tracing there is support for the folllowing environment
425             variables:
426              
427              
428              
429             =head2 C<DD_SERVICE_NAME>
430              
431             The name of a set of processes that do the same job. Used for grouping stats for
432             your application.
433              
434             B<default:> I<none>
435              
436              
437              
438             =head2 C<DD_ENV>
439              
440             Your application environment (for example, production, staging).
441              
442             B<default:> I<none>
443              
444              
445              
446             =head2 C<DD_HOSTNAME>
447              
448             Manually set the hostname to use for metrics if autodetection fails, or when
449             running the Datadog Cluster Agent.
450              
451              
452              
453             =head2 C<DD_VERSION>
454              
455             Your application version (for example, 2.5, 202003181415, 1.3-alpha).
456              
457             B<default:> I<none>
458              
459              
460              
461             =head1 SEE ALSO
462              
463             =over
464              
465             =item L<OpenTracing::Implementation::DataDog>
466              
467             Sending traces to DataDog using Agent.
468              
469             =item L<OpenTracing::Role::SpanContext>
470              
471             Role for OpenTracing Implementations.
472              
473             =back
474              
475              
476              
477             =head1 AUTHOR
478              
479             Theo van Hoesel <tvanhoesel@perceptyx.com>
480              
481              
482              
483             =head1 COPYRIGHT AND LICENSE
484              
485             'OpenTracing::Implementation::DataDog'
486             is Copyright (C) 2019 .. 2021, Perceptyx Inc
487              
488             This library is free software; you can redistribute it and/or modify it under
489             the terms of the Artistic License 2.0.
490              
491             This package is distributed in the hope that it will be useful, but it is
492             provided "as is" and without any express or implied warranties.
493              
494             For details, see the full text of the license in the file LICENSE.
495              
496              
497             =cut
498              
499             1;