File Coverage

blib/lib/OpenTracing/Implementation/DataDog/SpanContext.pm
Criterion Covered Total %
statement 24 24 100.0
branch n/a
condition n/a
subroutine 10 10 100.0
pod 3 3 100.0
total 37 37 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.40.0.7-TRIAL';
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             );
21             #
22             # please do not add parameter values in the resource,
23             # use tags instead, like:
24             # $span->set_tag( client_id => $request->query_params('client_id') )
25              
26             =cut
27              
28 12     12   957038 use Moo;
  12         61552  
  12         81  
29 12     12   16525 use MooX::Enumeration;
  12         32771  
  12         78  
30 12     12   5020 use MooX::Attribute::ENV;
  12         73294  
  12         119  
31              
32             with 'OpenTracing::Role::SpanContext';
33              
34 12     12   6838 use OpenTracing::Implementation::DataDog::Utils qw/random_64bit_int/;
  12         41  
  12         685  
35              
36 12     12   5951 use Sub::Trigger::Lock;
  12         39723  
  12         163  
37 12     12   9591 use Types::Common::String qw/NonEmptyStr/;
  12         1144091  
  12         168  
38 12     12   7888 use Types::Standard qw/Int/;
  12         33  
  12         81  
39              
40              
41              
42             =head1 DESCRIPTION
43              
44             This is a L<OpenTracing SpanContext|OpenTracing::Interface::SpanContext>
45             compliant implementation with DataDog specific extentions
46              
47             =cut
48              
49              
50              
51             =head1 EXTENDED ATTRIBUTES
52              
53             =cut
54              
55              
56              
57             =head2 C<trace_id>
58              
59             DataDog requires this to be a unsigned 64-bit integer
60              
61             =cut
62              
63             has '+trace_id' => (
64             is =>'ro',
65             isa => Int,
66             default => sub{ random_64bit_int() }
67             );
68              
69              
70              
71             =head2 C<span_id>
72              
73             DataDog requires this to be a unsigned 64-bit integer
74              
75             =cut
76              
77             has '+span_id' => (
78             is =>'ro',
79             isa => Int,
80             default => sub{ random_64bit_int() }
81             );
82              
83              
84              
85             =head1 DATADOG SPECIFIC ATTRIBUTES
86              
87             =cut
88              
89              
90              
91             =head2 C<service_name>
92              
93             A required C<NonEmptyString> where C<length <= 100>.
94              
95             Defaults to the value of the C<DD_SERVICE_NAME> environment variable if set.
96              
97             The service-name will usually be the name of the application and could easilly
98             be set by a intergration solution.
99              
100             =cut
101              
102             has service_name => (
103             is => 'ro',
104             env_key => 'DD_SERVICE_NAME',
105             required => 1,
106             isa => NonEmptyStr->where( 'length($_) <= 100' ),
107             reader => 'get_service_name',
108             trigger => Lock,
109             );
110              
111              
112              
113             =head2 C<service_type>
114              
115             An enumeration on C<web>, C<db>, C<cache>, and C<custom>, which is the default.
116              
117             DataDog has four different service types to make it more easy to visualize the
118             data. See L<Service List at DataDog HQ|
119             https://docs.datadoghq.com/tracing/visualization/services_list/#services-types>
120              
121             =cut
122              
123             has service_type => (
124             is => 'ro',
125             default => 'custom',
126             enum => [qw/web db cache custom/],
127             handles => 2, # such that we have `service_type_is_...`
128             reader => 'get_service_type',
129             trigger => Lock,
130             );
131              
132              
133              
134             =head2 C<resource_name>
135              
136             A required C<NonEmptyString> where C<length <= 5000>.
137              
138             Good candidates for resource names are URL paths or databasenames and or tables.
139              
140             =cut
141              
142             has resource_name => (
143             is => 'ro',
144             isa => NonEmptyStr->where( 'length($_) <= 5000' ),
145             required => 1,
146             reader => 'get_resource_name',
147             trigger => Lock,
148             );
149              
150              
151              
152             =head1 CONSTRUCTORS
153              
154             =head2 Warning:
155              
156             Constructors are not to be used outside an implementation, they are not part of
157             the L<OpenTracing API|OpenTracing::Interface>.
158              
159             Only an integration solution should be bothered creating a 'root context'.
160              
161             =head2 new
162              
163             my $span_context = SpanContext->new(
164             service_name => "MyFancyService",
165             resource_name => "/clients/{client_id}/contactdetails",
166             baggage_items => { $key => $value, .. },
167             );
168              
169             Creates a new SpanContext object;
170              
171              
172              
173             =head1 INSTANCE METHODS
174              
175             Besides all methods available from the L<OpenTracing::Roles::SpanContext>, the
176             following are DataDog specific added methods.
177              
178             =cut
179              
180              
181              
182             =head2 C<service_type_is_web>
183              
184             Returns a C<Bool> wether or not the L<service_type> is set to C<web>.
185              
186             =head2 C<service_type_is_db>
187              
188             Returns a C<Bool> wether or not the L<service_type> is set to C<db>.
189              
190             =head2 C<service_type_is_cache>
191              
192             Returns a C<Bool> wether or not the L<service_type> is set to C<cache>.
193              
194             =head2 C<service_type_is_ciustom>
195              
196             Returns a C<Bool> wether or not the L<service_type> is set to C<custom>.
197              
198             =cut
199              
200              
201              
202             =head1 CLONE METHODS
203              
204             Since C<SpanContext> is supposed to be an in-mutable object, and there are some
205             occasions that DataDog settings need to added (i.e. a root span), there are a
206             few cloning methods provided:
207              
208             =cut
209              
210              
211              
212             =head2 C<with_service_name>
213              
214             Creates a cloned object, with a new value for C<service_name>.
215              
216             $span_context_new = $root_span->with_service_name( 'MyAwesomeApp' );
217              
218             =head3 Required Positional Parameter(s)
219              
220             =over
221              
222             =item C<service_name>
223              
224             A C<NonEmptyString> where C<length <= 100>.
225              
226             =back
227              
228             =head3 Returns
229              
230             A cloned C<DataDog::SpanContext>
231              
232             =cut
233              
234 1     1 1 527 sub with_service_name { $_[0]->clone_with( service_name => $_[1] ) }
235              
236              
237              
238             =head2 C<with_service_type>
239              
240             Creates a cloned object, with a new value for C<service_type>.
241              
242             $span_context_new = $root_span->with_service_type( 'cache' );
243              
244             =head3 Required Positional Parameter(s)
245              
246             =over
247              
248             =item C<service_type>
249              
250             An enumeration on C<web>, C<db>, C<cache>, and C<custom>
251              
252             =back
253              
254             =head3 Returns
255              
256             A cloned C<DataDog::SpanContext>
257              
258             =cut
259              
260 1     1 1 587 sub with_service_type { $_[0]->clone_with( service_type => $_[1] ) }
261              
262              
263              
264             =head2 C<with_resource_name>
265              
266             Creates a cloned object, with a new value for C<resource_name>.
267              
268             $span_context_new = $root_span->with_resource_name( 'clients/?/index.cgi' );
269              
270             =head3 Required Positional Parameter(s)
271              
272             =over
273              
274             =item C<resource_name>
275              
276             A C<NonEmptyString> where C<length <= 5000>.
277              
278             =back
279              
280             =head3 Returns
281              
282             A cloned C<DataDog::SpanContext>
283              
284             =cut
285              
286 1     1 1 570 sub with_resource_name { $_[0]->clone_with( resource_name => $_[1] ) }
287              
288              
289              
290             =head1 SEE ALSO
291              
292             =over
293              
294             =item L<OpenTracing::Implementation::DataDog>
295              
296             Sending traces to DataDog using Agent.
297              
298             =item L<OpenTracing::Role::SpanContext>
299              
300             Role for OpenTracing Implementations.
301              
302             =back
303              
304              
305              
306             =head1 AUTHOR
307              
308             Theo van Hoesel <tvanhoesel@perceptyx.com>
309              
310              
311              
312             =head1 COPYRIGHT AND LICENSE
313              
314             'OpenTracing::Implementation::DataDog'
315             is Copyright (C) 2019 .. 2020, Perceptyx Inc
316              
317             This library is free software; you can redistribute it and/or modify it under
318             the terms of the Artistic License 2.0.
319              
320             This package is distributed in the hope that it will be useful, but it is
321             provided "as is" and without any express or implied warranties.
322              
323             For details, see the full text of the license in the file LICENSE.
324              
325              
326             =cut
327              
328             1;