-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathGettingStarted.html
4026 lines (4017 loc) · 266 KB
/
GettingStarted.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
<!DOCTYPE html>
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<meta charset="utf-8">
<link rel="stylesheet" href="toc.css">
<link rel="stylesheet" href="bootstrap/css/bootstrap.min.css">
</head>
<body>
<ul class="toc"><li>
<a href="#datadog-ruby-trace-client">Datadog Ruby Trace Client</a><ul>
<li>
<a href="#getting-started">Getting started</a><ul></ul>
</li>
<li>
<a href="#compatibility-requirements">Compatibility requirements</a><ul></ul>
</li>
<li>
<a href="#installation">Installation</a><ul>
<li>
<a href="#setup-the-datadog-agent-for-tracing">Setup the Datadog Agent for tracing</a><ul></ul>
</li>
<li>
<a href="#instrument-your-application">Instrument your application</a><ul></ul>
</li>
<li>
<a href="#connect-your-application-to-the-datadog-agent">Connect your application to the Datadog Agent</a><ul></ul>
</li>
<li>
<a href="#final-steps-for-installation">Final steps for installation</a><ul></ul>
</li>
</ul>
</li>
<li>
<a href="#manual-instrumentation">Manual Instrumentation</a><ul>
<li>
<a href="#asynchronous-tracing">Asynchronous tracing</a><ul></ul>
</li>
<li>
<a href="#enriching-traces-from-nested-methods">Enriching traces from nested methods</a><ul></ul>
</li>
</ul>
</li>
<li>
<a href="#integration-instrumentation">Integration instrumentation</a><ul>
<li>
<a href="#action-cable">Action Cable</a><ul></ul>
</li>
<li>
<a href="#action-mailer">Action Mailer</a><ul></ul>
</li>
<li>
<a href="#action-pack">Action Pack</a><ul></ul>
</li>
<li>
<a href="#action-view">Action View</a><ul></ul>
</li>
<li>
<a href="#active-job">Active Job</a><ul></ul>
</li>
<li>
<a href="#active-model-serializers">Active Model Serializers</a><ul></ul>
</li>
<li>
<a href="#active-record">Active Record</a><ul></ul>
</li>
<li>
<a href="#active-support">Active Support</a><ul></ul>
</li>
<li>
<a href="#aws">AWS</a><ul></ul>
</li>
<li>
<a href="#concurrent-ruby">Concurrent Ruby</a><ul></ul>
</li>
<li>
<a href="#cucumber">Cucumber</a><ul></ul>
</li>
<li>
<a href="#dalli">Dalli</a><ul></ul>
</li>
<li>
<a href="#delayedjob">DelayedJob</a><ul></ul>
</li>
<li>
<a href="#elasticsearch">Elasticsearch</a><ul></ul>
</li>
<li>
<a href="#ethon">Ethon</a><ul></ul>
</li>
<li>
<a href="#excon">Excon</a><ul></ul>
</li>
<li>
<a href="#faraday">Faraday</a><ul></ul>
</li>
<li>
<a href="#grape">Grape</a><ul></ul>
</li>
<li>
<a href="#graphql">GraphQL</a><ul></ul>
</li>
<li>
<a href="#grpc">gRPC</a><ul></ul>
</li>
<li>
<a href="#hanami">hanami</a><ul></ul>
</li>
<li>
<a href="#http.rb">http.rb</a><ul></ul>
</li>
<li>
<a href="#httpclient">httpclient</a><ul></ul>
</li>
<li>
<a href="#httpx">httpx</a><ul></ul>
</li>
<li>
<a href="#kafka">Kafka</a><ul></ul>
</li>
<li>
<a href="#minitest">Minitest</a><ul></ul>
</li>
<li>
<a href="#mongodb">MongoDB</a><ul></ul>
</li>
<li>
<a href="#mysql2">MySQL2</a><ul></ul>
</li>
<li>
<a href="#nethttp">Net/HTTP</a><ul></ul>
</li>
<li>
<a href="#opensearch">OpenSearch</a><ul></ul>
</li>
<li>
<a href="#postgres">Postgres</a><ul></ul>
</li>
<li>
<a href="#presto">Presto</a><ul></ul>
</li>
<li>
<a href="#qless">Qless</a><ul></ul>
</li>
<li>
<a href="#que">Que</a><ul></ul>
</li>
<li>
<a href="#racecar">Racecar</a><ul></ul>
</li>
<li>
<a href="#rack">Rack</a><ul></ul>
</li>
<li>
<a href="#rails">Rails</a><ul></ul>
</li>
<li>
<a href="#rake">Rake</a><ul></ul>
</li>
<li>
<a href="#redis">Redis</a><ul></ul>
</li>
<li>
<a href="#resque">Resque</a><ul></ul>
</li>
<li>
<a href="#rest-client">Rest Client</a><ul></ul>
</li>
<li>
<a href="#roda">Roda</a><ul></ul>
</li>
<li>
<a href="#rspec">RSpec</a><ul></ul>
</li>
<li>
<a href="#sequel">Sequel</a><ul></ul>
</li>
<li>
<a href="#shoryuken">Shoryuken</a><ul></ul>
</li>
<li>
<a href="#sidekiq">Sidekiq</a><ul></ul>
</li>
<li>
<a href="#sinatra">Sinatra</a><ul></ul>
</li>
<li>
<a href="#sneakers">Sneakers</a><ul></ul>
</li>
<li>
<a href="#stripe">Stripe</a><ul></ul>
</li>
<li>
<a href="#sucker-punch">Sucker Punch</a><ul></ul>
</li>
<li>
<a href="#trilogy">Trilogy</a><ul></ul>
</li>
</ul>
</li>
<li>
<a href="#additional-configuration">Additional configuration</a><ul>
<li>
<a href="#sampling">Sampling</a><ul></ul>
</li>
<li>
<a href="#distributed-tracing">Distributed Tracing</a><ul></ul>
</li>
<li>
<a href="#http-request-queuing">HTTP request queuing</a><ul></ul>
</li>
<li>
<a href="#processing-pipeline">Processing Pipeline</a><ul></ul>
</li>
<li>
<a href="#trace-correlation">Trace correlation</a><ul></ul>
</li>
<li>
<a href="#configuring-the-transport-layer">Configuring the transport layer</a><ul></ul>
</li>
<li>
<a href="#setting-the-time-provider">Setting the time provider</a><ul></ul>
</li>
<li>
<a href="#metrics">Metrics</a><ul></ul>
</li>
<li>
<a href="#opentracing">OpenTracing</a><ul></ul>
</li>
<li>
<a href="#profiling">Profiling</a><ul></ul>
</li>
</ul>
</li>
<li>
<a href="#known-issues-and-suggested-configurations">Known issues and suggested configurations</a><ul>
<li>
<a href="#payload-too-large">Payload too large</a><ul></ul>
</li>
<li>
<a href="#stack-level-too-deep">Stack level too deep</a><ul></ul>
</li>
<li>
<a href="#resque-workers-hang-on-exit">Resque workers hang on exit</a><ul></ul>
</li>
</ul>
</li>
</ul>
</li></ul>
<h1 id="datadog-ruby-trace-client">Datadog Ruby Trace Client</h1>
<p><code>ddtrace</code> is Datadog’s tracing client for Ruby. It is used to trace requests as they flow across web servers, databases and microservices so that developers have high visibility into bottlenecks and troublesome requests.</p>
<h2 id="getting-started">Getting started</h2>
<p><strong>If you’re upgrading from a 0.x version, check out our <a href="https://github.com/DataDog/dd-trace-rb/blob/master/docs/UpgradeGuide.md#from-0x-to-10">upgrade guide</a>.</strong></p>
<p>For the general APM documentation, see our <a href="https://docs.datadoghq.com/tracing/">setup documentation</a>.</p>
<p>For more information about what APM looks like once your application is sending information to Datadog, take a look at <a href="https://docs.datadoghq.com/tracing/glossary/">Terms and Concepts</a>.</p>
<p>For the library API documentation, see our <a href="https://www.rubydoc.info/gems/ddtrace/">YARD documentation</a>.</p>
<p>To contribute, check out the <a href="https://github.com/DataDog/dd-trace-rb/blob/master/CONTRIBUTING.md">contribution guidelines</a> and <a href="https://github.com/DataDog/dd-trace-rb/blob/master/docs/DevelopmentGuide.md">development guide</a>.</p>
<h2 id="compatibility-requirements">Compatibility requirements</h2>
<p>For a full list of Datadog’s Ruby library support, see <a href="https://docs.datadoghq.com/tracing/trace_collection/compatibility/ruby/">Compatibility Requirements</a>.</p>
<h2 id="installation">Installation</h2>
<p>Adding tracing to your Ruby application only takes a few quick steps:</p>
<ol type="1">
<li>Setup the Datadog Agent for tracing</li>
<li>Instrument your application</li>
<li>Connect your application to the Datadog Agent</li>
</ol>
<h3 id="setup-the-datadog-agent-for-tracing">Setup the Datadog Agent for tracing</h3>
<p>Before installing <code>ddtrace</code>, <a href="https://docs.datadoghq.com/agent/">install the Datadog Agent</a>, to which <code>ddtrace</code> will send trace data.</p>
<p>Then configure the Datadog Agent to accept traces. To do this, either:</p>
<ul>
<li>Set <code>DD_APM_ENABLED=true</code> in the Agent’s environment</li>
</ul>
<p>OR</p>
<ul>
<li>Add <code>apm_enabled: true</code> to the <a href="https://docs.datadoghq.com/agent/guide/agent-configuration-files/?tab=agentv6v7#agent-main-configuration-file">Agent’s configuration file</a>
</li>
</ul>
<p><em>Additionally, in containerized environments…</em></p>
<ul>
<li>Set <code>DD_APM_NON_LOCAL_TRAFFIC=true</code> in the Agent’s environment</li>
</ul>
<p>OR</p>
<ul>
<li>Add <code>apm_non_local_traffic: true</code> to the <a href="https://docs.datadoghq.com/agent/guide/agent-configuration-files/?tab=agentv6v7#agent-main-configuration-file">Agent’s configuration file</a>.</li>
</ul>
<p>See the specific setup instructions for <a href="https://docs.datadoghq.com/agent/docker/apm/?tab=ruby">Docker</a>, <a href="https://docs.datadoghq.com/agent/kubernetes/apm/?tab=helm">Kubernetes</a>, <a href="https://docs.datadoghq.com/agent/amazon_ecs/apm/?tab=ruby">Amazon ECS</a> or <a href="https://docs.datadoghq.com/integrations/ecs_fargate/#trace-collection">Fargate</a> to ensure that the Agent is configured to receive traces in a containerized environment.</p>
<h4 id="configuring-trace-data-ingestion">Configuring trace data ingestion</h4>
<p>The Datadog Agent will listen for traces via HTTP on port <code>8126</code> by default.</p>
<p>You may change the protocol or port the Agent listens for trace data using the following:</p>
<p><strong>For HTTP over TCP</strong>:</p>
<ul>
<li>Set <code>DD_APM_RECEIVER_PORT=<port></code> in the Agent’s environment</li>
</ul>
<p>OR</p>
<ul>
<li>Add <code>apm_config: receiver_port: <port></code> to the <a href="https://docs.datadoghq.com/agent/guide/agent-configuration-files/?tab=agentv6v7#agent-main-configuration-file">Agent’s configuration file</a>
</li>
</ul>
<p><strong>For Unix Domain Socket (UDS)</strong>:</p>
<ul>
<li>Set <code>DD_APM_RECEIVER_SOCKET=<path-to-socket-file></code>
</li>
</ul>
<p>OR</p>
<ul>
<li>Add <code>apm_config: receiver_socket: <path-to-socket-file></code> to the <a href="https://docs.datadoghq.com/agent/guide/agent-configuration-files/?tab=agentv6v7#agent-main-configuration-file">Agent’s configuration file</a>
</li>
</ul>
<h3 id="instrument-your-application">Instrument your application</h3>
<h4 id="rails-or-hanami-applications">Rails or Hanami applications</h4>
<ol type="1">
<li>
<p>Add the <code>ddtrace</code> gem to your Gemfile:</p>
<div class="sourceCode" id="cb1"><pre class="sourceCode ruby"><code class="sourceCode ruby"><span id="cb1-1"><a href="#cb1-1" aria-hidden="true"></a>source <span class="st">'https://rubygems.org'</span></span>
<span id="cb1-2"><a href="#cb1-2" aria-hidden="true"></a>gem <span class="st">'ddtrace'</span>, require: <span class="st">'ddtrace/auto_instrument'</span></span></code></pre></div>
</li>
<li><p>Install the gem with <code>bundle install</code></p></li>
<li>
<p>Create a <code>config/initializers/datadog.rb</code> file containing:</p>
<div class="sourceCode" id="cb2"><pre class="sourceCode ruby"><code class="sourceCode ruby"><span id="cb2-1"><a href="#cb2-1" aria-hidden="true"></a><span class="dt">Datadog</span>.configure <span class="kw">do</span> |c|</span>
<span id="cb2-2"><a href="#cb2-2" aria-hidden="true"></a> <span class="co"># Add additional configuration here.</span></span>
<span id="cb2-3"><a href="#cb2-3" aria-hidden="true"></a> <span class="co"># Activate integrations, change tracer settings, etc...</span></span>
<span id="cb2-4"><a href="#cb2-4" aria-hidden="true"></a><span class="kw">end</span></span></code></pre></div>
<p>Using this block you can:</p>
<ul>
<li><a href="#additional-configuration">Add additional configuration settings</a></li>
<li><a href="#integration-instrumentation">Activate or reconfigure instrumentation</a></li>
</ul>
</li>
</ol>
<h4 id="other-ruby-applications">Other Ruby applications</h4>
<p>If your application does not use the supported gems (Rails or Hanami) above, you can set it up as follows:</p>
<ol type="1">
<li>
<p>Add the <code>ddtrace</code> gem to your Gemfile:</p>
<div class="sourceCode" id="cb3"><pre class="sourceCode ruby"><code class="sourceCode ruby"><span id="cb3-1"><a href="#cb3-1" aria-hidden="true"></a>source <span class="st">'https://rubygems.org'</span></span>
<span id="cb3-2"><a href="#cb3-2" aria-hidden="true"></a>gem <span class="st">'ddtrace'</span></span></code></pre></div>
</li>
<li><p>Install the gem with <code>bundle install</code></p></li>
<li><p><code>require</code> any <a href="#integration-instrumentation">supported libraries or frameworks</a> that should be instrumented.</p></li>
<li>
<p>Add <code>require 'ddtrace/auto_instrument'</code> to your application. <em>Note:</em> This must be done <em>after</em> requiring any supported libraries or frameworks.</p>
<div class="sourceCode" id="cb4"><pre class="sourceCode ruby"><code class="sourceCode ruby"><span id="cb4-1"><a href="#cb4-1" aria-hidden="true"></a><span class="co"># Example frameworks and libraries</span></span>
<span id="cb4-2"><a href="#cb4-2" aria-hidden="true"></a>require <span class="st">'sinatra'</span></span>
<span id="cb4-3"><a href="#cb4-3" aria-hidden="true"></a>require <span class="st">'faraday'</span></span>
<span id="cb4-4"><a href="#cb4-4" aria-hidden="true"></a>require <span class="st">'redis'</span></span>
<span id="cb4-5"><a href="#cb4-5" aria-hidden="true"></a></span>
<span id="cb4-6"><a href="#cb4-6" aria-hidden="true"></a>require <span class="st">'ddtrace/auto_instrument'</span></span></code></pre></div>
</li>
<li>
<p>Add a configuration block to your application:</p>
<div class="sourceCode" id="cb5"><pre class="sourceCode ruby"><code class="sourceCode ruby"><span id="cb5-1"><a href="#cb5-1" aria-hidden="true"></a><span class="dt">Datadog</span>.configure <span class="kw">do</span> |c|</span>
<span id="cb5-2"><a href="#cb5-2" aria-hidden="true"></a> <span class="co"># Add additional configuration here.</span></span>
<span id="cb5-3"><a href="#cb5-3" aria-hidden="true"></a> <span class="co"># Activate integrations, change tracer settings, etc...</span></span>
<span id="cb5-4"><a href="#cb5-4" aria-hidden="true"></a><span class="kw">end</span></span></code></pre></div>
<p>Using this block you can:</p>
<ul>
<li><a href="#additional-configuration">Add additional configuration settings</a></li>
<li><a href="#integration-instrumentation">Activate or reconfigure instrumentation</a></li>
</ul>
</li>
</ol>
<h4 id="configuring-opentracing">Configuring OpenTracing</h4>
<ol type="1">
<li>
<p>Add the <code>ddtrace</code> gem to your Gemfile:</p>
<div class="sourceCode" id="cb6"><pre class="sourceCode ruby"><code class="sourceCode ruby"><span id="cb6-1"><a href="#cb6-1" aria-hidden="true"></a>source <span class="st">'https://rubygems.org'</span></span>
<span id="cb6-2"><a href="#cb6-2" aria-hidden="true"></a>gem <span class="st">'ddtrace'</span></span></code></pre></div>
</li>
<li><p>Install the gem with <code>bundle install</code></p></li>
<li>
<p>To your OpenTracing configuration file, add the following:</p>
<div class="sourceCode" id="cb7"><pre class="sourceCode ruby"><code class="sourceCode ruby"><span id="cb7-1"><a href="#cb7-1" aria-hidden="true"></a>require <span class="st">'opentracing'</span></span>
<span id="cb7-2"><a href="#cb7-2" aria-hidden="true"></a>require <span class="st">'datadog/tracing'</span></span>
<span id="cb7-3"><a href="#cb7-3" aria-hidden="true"></a>require <span class="st">'datadog/opentracer'</span></span>
<span id="cb7-4"><a href="#cb7-4" aria-hidden="true"></a></span>
<span id="cb7-5"><a href="#cb7-5" aria-hidden="true"></a><span class="co"># Activate the Datadog tracer for OpenTracing</span></span>
<span id="cb7-6"><a href="#cb7-6" aria-hidden="true"></a><span class="dt">OpenTracing</span>.global_tracer = <span class="dt">Datadog</span>::<span class="dt">OpenTracer</span>::<span class="dt">Tracer</span>.new</span></code></pre></div>
</li>
<li>
<p>Add a configuration block to your application:</p>
<div class="sourceCode" id="cb8"><pre class="sourceCode ruby"><code class="sourceCode ruby"><span id="cb8-1"><a href="#cb8-1" aria-hidden="true"></a><span class="dt">Datadog</span>.configure <span class="kw">do</span> |c|</span>
<span id="cb8-2"><a href="#cb8-2" aria-hidden="true"></a> <span class="co"># Configure the Datadog tracer here.</span></span>
<span id="cb8-3"><a href="#cb8-3" aria-hidden="true"></a> <span class="co"># Activate integrations, change tracer settings, etc...</span></span>
<span id="cb8-4"><a href="#cb8-4" aria-hidden="true"></a> <span class="co"># By default without additional configuration,</span></span>
<span id="cb8-5"><a href="#cb8-5" aria-hidden="true"></a> <span class="co"># no additional integrations will be traced, only</span></span>
<span id="cb8-6"><a href="#cb8-6" aria-hidden="true"></a> <span class="co"># what you have instrumented with OpenTracing.</span></span>
<span id="cb8-7"><a href="#cb8-7" aria-hidden="true"></a><span class="kw">end</span></span></code></pre></div>
<p>Using this block you can:</p>
<ul>
<li><a href="#additional-configuration">Add additional Datadog configuration settings</a></li>
<li><a href="#integration-instrumentation">Activate or reconfigure Datadog instrumentation</a></li>
</ul>
</li>
</ol>
<h4 id="configuring-opentelemetry">Configuring OpenTelemetry</h4>
<p>You can send OpenTelemetry traces directly to the Datadog Agent (without <code>ddtrace</code>) by using OTLP. Check out our documentation on <a href="https://docs.datadoghq.com/tracing/setup_overview/open_standards/#otlp-ingest-in-datadog-agent">OTLP ingest in the Datadog Agent</a> for details.</p>
<h3 id="connect-your-application-to-the-datadog-agent">Connect your application to the Datadog Agent</h3>
<p>By default, <code>ddtrace</code> will connect to the Agent using the first available settings in the listed priority:</p>
<ol type="1">
<li>Via any explicitly provided configuration settings (hostname/port/transport)</li>
<li>Via Unix Domain Socket (UDS) located at <code>/var/run/datadog/apm.socket</code>
</li>
<li>Via HTTP over TCP to <code>127.0.0.1:8126</code>
</li>
</ol>
<p>If your Datadog Agent is listening at any of these locations, no further configuration should be required.</p>
<p>If your Agent runs on a different host or container than your application, or you would like to send traces via a different protocol, you will need to configure your application accordingly.</p>
<ul>
<li><a href="#changing-default-agent-hostname-and-port">How to send trace data via HTTP over TCP to Agent</a></li>
<li><a href="#using-the-unix-domain-socket-uds-adapter">How to send trace data via Unix Domain Socket (UDS) to Agent</a></li>
</ul>
<h3 id="final-steps-for-installation">Final steps for installation</h3>
<p>After setting up, your services will appear on the <a href="https://app.datadoghq.com/apm/services">APM services page</a> within a few minutes. Learn more about <a href="https://docs.datadoghq.com/tracing/glossary/">using the APM UI</a>.</p>
<h2 id="manual-instrumentation">Manual Instrumentation</h2>
<p>If you aren’t using a supported framework instrumentation, you may want to manually instrument your code.</p>
<p>To trace any Ruby code, you can use the <code>Datadog::Tracing.trace</code> method:</p>
<div class="sourceCode" id="cb9"><pre class="sourceCode ruby"><code class="sourceCode ruby"><span id="cb9-1"><a href="#cb9-1" aria-hidden="true"></a><span class="dt">Datadog</span>::<span class="dt">Tracing</span>.trace(name, **options) <span class="kw">do</span> |span, trace|</span>
<span id="cb9-2"><a href="#cb9-2" aria-hidden="true"></a> <span class="co"># Wrap this block around the code you want to instrument</span></span>
<span id="cb9-3"><a href="#cb9-3" aria-hidden="true"></a> <span class="co"># Additionally, you can modify the span here.</span></span>
<span id="cb9-4"><a href="#cb9-4" aria-hidden="true"></a> <span class="co"># e.g. Change the resource name, set tags, etc...</span></span>
<span id="cb9-5"><a href="#cb9-5" aria-hidden="true"></a><span class="kw">end</span></span></code></pre></div>
<p>Where <code>name</code> should be a <code>String</code> that describes the generic kind of operation being done (e.g. <code>'web.request'</code>, or <code>'request.parse'</code>)</p>
<p>And <code>options</code> are the following optional keyword arguments:</p>
<table style="width:100%;">
<colgroup>
<col style="width: 34%">
<col style="width: 52%">
<col style="width: 6%">
<col style="width: 6%">
</colgroup>
<thead>
<tr class="header">
<th>Key</th>
<th>Type</th>
<th>Description</th>
<th>Default</th>
</tr>
</thead>
<tbody>
<tr class="odd">
<td><code>autostart</code></td>
<td><code>Bool</code></td>
<td>Whether the time measurement should be started automatically. If <code>false</code>, user must call <code>span.start</code>.</td>
<td><code>true</code></td>
</tr>
<tr class="even">
<td><code>continue_from</code></td>
<td><code>Datadog::TraceDigest</code></td>
<td>Continues a trace that originated from another execution context. TraceDigest describes the continuation point.</td>
<td><code>nil</code></td>
</tr>
<tr class="odd">
<td><code>on_error</code></td>
<td><code>Proc</code></td>
<td>Overrides error handling behavior, when a span raises an error. Provided <code>span</code> and <code>error</code> as arguments. Sets error on the span by default.</td>
<td><code>proc { |span, error| span.set_error(error) unless span.nil? }</code></td>
</tr>
<tr class="even">
<td><code>resource</code></td>
<td><code>String</code></td>
<td>Name of the resource or action being operated on. Traces with the same resource value will be grouped together for the purpose of metrics (but still independently viewable.) Usually domain specific, such as a URL, query, request, etc. (e.g. <code>'Article#submit'</code>, <code>http://example.com/articles/list</code>.)</td>
<td>
<code>name</code> of Span.</td>
</tr>
<tr class="odd">
<td><code>service</code></td>
<td><code>String</code></td>
<td>The service name which this span belongs (e.g. <code>'my-web-service'</code>)</td>
<td>Tracer <code>default-service</code>, <code>$PROGRAM_NAME</code> or <code>'ruby'</code>
</td>
</tr>
<tr class="even">
<td><code>start_time</code></td>
<td><code>Time</code></td>
<td>When the span actually starts. Useful when tracing events that have already happened.</td>
<td><code>Time.now</code></td>
</tr>
<tr class="odd">
<td><code>tags</code></td>
<td><code>Hash</code></td>
<td>Extra tags which should be added to the span.</td>
<td><code>{}</code></td>
</tr>
<tr class="even">
<td><code>type</code></td>
<td><code>String</code></td>
<td>The type of the span (such as <code>'http'</code>, <code>'db'</code>, etc.)</td>
<td><code>nil</code></td>
</tr>
</tbody>
</table>
<p>It’s highly recommended you set both <code>service</code> and <code>resource</code> at a minimum. Spans without a <code>service</code> or <code>resource</code> as <code>nil</code> will be discarded by the Datadog agent.</p>
<p>Example of manual instrumentation in action:</p>
<div class="sourceCode" id="cb10"><pre class="sourceCode ruby"><code class="sourceCode ruby"><span id="cb10-1"><a href="#cb10-1" aria-hidden="true"></a>get <span class="st">'/posts'</span> <span class="kw">do</span></span>
<span id="cb10-2"><a href="#cb10-2" aria-hidden="true"></a> <span class="dt">Datadog</span>::<span class="dt">Tracing</span>.trace(<span class="st">'web.request'</span>, <span class="st">service: 'my-blog'</span>, <span class="st">resource: 'GET /posts'</span>) <span class="kw">do</span> |span|</span>
<span id="cb10-3"><a href="#cb10-3" aria-hidden="true"></a> <span class="co"># Trace the activerecord call</span></span>
<span id="cb10-4"><a href="#cb10-4" aria-hidden="true"></a> <span class="dt">Datadog</span>::<span class="dt">Tracing</span>.trace(<span class="st">'posts.fetch'</span>) <span class="kw">do</span></span>
<span id="cb10-5"><a href="#cb10-5" aria-hidden="true"></a> <span class="ot">@posts</span> = <span class="dt">Posts</span>.order(<span class="st">created_at: :desc</span>).limit(<span class="dv">10</span>)</span>
<span id="cb10-6"><a href="#cb10-6" aria-hidden="true"></a> <span class="kw">end</span></span>
<span id="cb10-7"><a href="#cb10-7" aria-hidden="true"></a></span>
<span id="cb10-8"><a href="#cb10-8" aria-hidden="true"></a> <span class="co"># Add some APM tags</span></span>
<span id="cb10-9"><a href="#cb10-9" aria-hidden="true"></a> span.set_tag(<span class="st">'http.method'</span>, request.request_method)</span>
<span id="cb10-10"><a href="#cb10-10" aria-hidden="true"></a> span.set_tag(<span class="st">'posts.count'</span>, <span class="ot">@posts</span>.length)</span>
<span id="cb10-11"><a href="#cb10-11" aria-hidden="true"></a></span>
<span id="cb10-12"><a href="#cb10-12" aria-hidden="true"></a> <span class="co"># Trace the template rendering</span></span>
<span id="cb10-13"><a href="#cb10-13" aria-hidden="true"></a> <span class="dt">Datadog</span>::<span class="dt">Tracing</span>.trace(<span class="st">'template.render'</span>) <span class="kw">do</span></span>
<span id="cb10-14"><a href="#cb10-14" aria-hidden="true"></a> erb <span class="st">:index</span></span>
<span id="cb10-15"><a href="#cb10-15" aria-hidden="true"></a> <span class="kw">end</span></span>
<span id="cb10-16"><a href="#cb10-16" aria-hidden="true"></a> <span class="kw">end</span></span>
<span id="cb10-17"><a href="#cb10-17" aria-hidden="true"></a><span class="kw">end</span></span></code></pre></div>
<h3 id="asynchronous-tracing">Asynchronous tracing</h3>
<p>It might not always be possible to wrap <code>Datadog::Tracing.trace</code> around a block of code. Some event or notification based instrumentation might only notify you when an event begins or ends.</p>
<p>To trace these operations, you can trace code asynchronously by calling <code>Datadog::Tracing.trace</code> without a block:</p>
<div class="sourceCode" id="cb11"><pre class="sourceCode ruby"><code class="sourceCode ruby"><span id="cb11-1"><a href="#cb11-1" aria-hidden="true"></a><span class="co"># Some instrumentation framework calls this after an event finishes...</span></span>
<span id="cb11-2"><a href="#cb11-2" aria-hidden="true"></a><span class="kw">def</span> db_query(start, finish, query)</span>
<span id="cb11-3"><a href="#cb11-3" aria-hidden="true"></a> span = <span class="dt">Datadog</span>::<span class="dt">Tracing</span>.trace(<span class="st">'database.query'</span>, <span class="st">start_time: </span>start)</span>
<span id="cb11-4"><a href="#cb11-4" aria-hidden="true"></a> span.resource = query</span>
<span id="cb11-5"><a href="#cb11-5" aria-hidden="true"></a> span.finish(finish)</span>
<span id="cb11-6"><a href="#cb11-6" aria-hidden="true"></a><span class="kw">end</span></span></code></pre></div>
<p>Calling <code>Datadog::Tracing.trace</code> without a block will cause the function to return a <code>Datadog::Tracing::SpanOperation</code> that is started, but not finished. You can then modify this span however you wish, then close it <code>finish</code>.</p>
<p><em>You must not leave any unfinished spans.</em> If any spans are left open when the trace completes, the trace will be discarded. You can <a href="#additional-configuration">activate debug mode</a> to check for warnings if you suspect this might be happening.</p>
<p>To avoid this scenario when handling start/finish events, you can use <code>Datadog::Tracing.active_span</code> to get the current active span.</p>
<div class="sourceCode" id="cb12"><pre class="sourceCode ruby"><code class="sourceCode ruby"><span id="cb12-1"><a href="#cb12-1" aria-hidden="true"></a><span class="co"># e.g. ActiveSupport::Notifications calls this when an event starts</span></span>
<span id="cb12-2"><a href="#cb12-2" aria-hidden="true"></a><span class="kw">def</span> start(name, id, payload)</span>
<span id="cb12-3"><a href="#cb12-3" aria-hidden="true"></a> <span class="co"># Start a span</span></span>
<span id="cb12-4"><a href="#cb12-4" aria-hidden="true"></a> <span class="dt">Datadog</span>::<span class="dt">Tracing</span>.trace(name)</span>
<span id="cb12-5"><a href="#cb12-5" aria-hidden="true"></a><span class="kw">end</span></span>
<span id="cb12-6"><a href="#cb12-6" aria-hidden="true"></a></span>
<span id="cb12-7"><a href="#cb12-7" aria-hidden="true"></a><span class="co"># e.g. ActiveSupport::Notifications calls this when an event finishes</span></span>
<span id="cb12-8"><a href="#cb12-8" aria-hidden="true"></a><span class="kw">def</span> finish(name, id, payload)</span>
<span id="cb12-9"><a href="#cb12-9" aria-hidden="true"></a> <span class="co"># Retrieve current active span (thread-safe)</span></span>
<span id="cb12-10"><a href="#cb12-10" aria-hidden="true"></a> current_span = <span class="dt">Datadog</span>::<span class="dt">Tracing</span>.active_span</span>
<span id="cb12-11"><a href="#cb12-11" aria-hidden="true"></a> <span class="kw">unless</span> current_span.nil?</span>
<span id="cb12-12"><a href="#cb12-12" aria-hidden="true"></a> current_span.resource = payload[<span class="st">:query</span>]</span>
<span id="cb12-13"><a href="#cb12-13" aria-hidden="true"></a> current_span.finish</span>
<span id="cb12-14"><a href="#cb12-14" aria-hidden="true"></a> <span class="kw">end</span></span>
<span id="cb12-15"><a href="#cb12-15" aria-hidden="true"></a><span class="kw">end</span></span></code></pre></div>
<h3 id="enriching-traces-from-nested-methods">Enriching traces from nested methods</h3>
<p>You can tag additional information to the current active span from any method. Note however that if the method is called and there is no span currently active <code>active_span</code> will be nil.</p>
<div class="sourceCode" id="cb13"><pre class="sourceCode ruby"><code class="sourceCode ruby"><span id="cb13-1"><a href="#cb13-1" aria-hidden="true"></a><span class="co"># e.g. adding tag to active span</span></span>
<span id="cb13-2"><a href="#cb13-2" aria-hidden="true"></a></span>
<span id="cb13-3"><a href="#cb13-3" aria-hidden="true"></a>current_span = <span class="dt">Datadog</span>::<span class="dt">Tracing</span>.active_span</span>
<span id="cb13-4"><a href="#cb13-4" aria-hidden="true"></a>current_span.set_tag(<span class="st">'my_tag'</span>, <span class="st">'my_value'</span>) <span class="kw">unless</span> current_span.nil?</span></code></pre></div>
<p>You can also get the current active trace using the <code>active_trace</code> method. This method will return <code>nil</code> if there is no active trace.</p>
<div class="sourceCode" id="cb14"><pre class="sourceCode ruby"><code class="sourceCode ruby"><span id="cb14-1"><a href="#cb14-1" aria-hidden="true"></a><span class="co"># e.g. accessing active trace</span></span>
<span id="cb14-2"><a href="#cb14-2" aria-hidden="true"></a></span>
<span id="cb14-3"><a href="#cb14-3" aria-hidden="true"></a>current_trace = <span class="dt">Datadog</span>::<span class="dt">Tracing</span>.active_trace</span></code></pre></div>
<h2 id="integration-instrumentation">Integration instrumentation</h2>
<p>Many popular libraries and frameworks are supported out-of-the-box, which can be auto-instrumented. Although they are not activated automatically, they can be easily activated and configured by using the <code>Datadog.configure</code> API:</p>
<div class="sourceCode" id="cb15"><pre class="sourceCode ruby"><code class="sourceCode ruby"><span id="cb15-1"><a href="#cb15-1" aria-hidden="true"></a><span class="dt">Datadog</span>.configure <span class="kw">do</span> |c|</span>
<span id="cb15-2"><a href="#cb15-2" aria-hidden="true"></a> <span class="co"># Activates and configures an integration</span></span>
<span id="cb15-3"><a href="#cb15-3" aria-hidden="true"></a> c.tracing.instrument <span class="st">:integration_name</span>, **options</span>
<span id="cb15-4"><a href="#cb15-4" aria-hidden="true"></a><span class="kw">end</span></span></code></pre></div>
<p><code>options</code> are keyword arguments for integration-specific configuration.</p>
<p>For a list of available integrations and their supported versions, see <a href="https://docs.datadoghq.com/tracing/trace_collection/compatibility/ruby#integrations">Ruby Integration Compatibility</a>.</p>
<p>For a list of configuration options for the available integrations, refer to the following:</p>
<h4 id="ci-visibility">CI Visibility</h4>
<p>For Datadog CI Visibility, library instrumentation can be activated and configured by using the following <code>Datadog.configure</code> API:</p>
<div class="sourceCode" id="cb16"><pre class="sourceCode ruby"><code class="sourceCode ruby"><span id="cb16-1"><a href="#cb16-1" aria-hidden="true"></a><span class="dt">Datadog</span>.configure <span class="kw">do</span> |c|</span>
<span id="cb16-2"><a href="#cb16-2" aria-hidden="true"></a> <span class="co"># Activates and configures an integration</span></span>
<span id="cb16-3"><a href="#cb16-3" aria-hidden="true"></a> c.ci.instrument <span class="st">:integration_name</span>, **options</span>
<span id="cb16-4"><a href="#cb16-4" aria-hidden="true"></a><span class="kw">end</span></span></code></pre></div>
<p><code>options</code> are keyword arguments for integration-specific configuration.</p>
<p>For a list of available integrations and their supported versions, see <a href="https://docs.datadoghq.com/tracing/trace_collection/compatibility/ruby#ci-visibility-integrations">Ruby CI Integration Compatibility</a></p>
<h3 id="action-cable">Action Cable</h3>
<p>The Action Cable integration traces broadcast messages and channel actions.</p>
<p>You can enable it through <code>Datadog.configure</code>:</p>
<div class="sourceCode" id="cb17"><pre class="sourceCode ruby"><code class="sourceCode ruby"><span id="cb17-1"><a href="#cb17-1" aria-hidden="true"></a>require <span class="st">'ddtrace'</span></span>
<span id="cb17-2"><a href="#cb17-2" aria-hidden="true"></a></span>
<span id="cb17-3"><a href="#cb17-3" aria-hidden="true"></a><span class="dt">Datadog</span>.configure <span class="kw">do</span> |c|</span>
<span id="cb17-4"><a href="#cb17-4" aria-hidden="true"></a> c.tracing.instrument <span class="st">:action_cable</span></span>
<span id="cb17-5"><a href="#cb17-5" aria-hidden="true"></a><span class="kw">end</span></span></code></pre></div>
<h3 id="action-mailer">Action Mailer</h3>
<p>The Action Mailer integration provides tracing for Rails 5 ActionMailer actions.</p>
<p>You can enable it through <code>Datadog.configure</code>:</p>
<div class="sourceCode" id="cb18"><pre class="sourceCode ruby"><code class="sourceCode ruby"><span id="cb18-1"><a href="#cb18-1" aria-hidden="true"></a>require <span class="st">'ddtrace'</span></span>
<span id="cb18-2"><a href="#cb18-2" aria-hidden="true"></a><span class="dt">Datadog</span>.configure <span class="kw">do</span> |c|</span>
<span id="cb18-3"><a href="#cb18-3" aria-hidden="true"></a> c.tracing.instrument <span class="st">:action_mailer</span>, **options</span>
<span id="cb18-4"><a href="#cb18-4" aria-hidden="true"></a><span class="kw">end</span></span></code></pre></div>
<p><code>options</code> are the following keyword arguments:</p>
<table>
<colgroup>
<col style="width: 14%">
<col style="width: 52%">
<col style="width: 33%">
</colgroup>
<thead>
<tr class="header">
<th>Key</th>
<th>Description</th>
<th>Default</th>
</tr>
</thead>
<tbody>
<tr class="odd">
<td><code>email_data</code></td>
<td>Whether or not to append additional email payload metadata to <code>action_mailer.deliver</code> spans. Fields include <code>['subject', 'to', 'from', 'bcc', 'cc', 'date', 'perform_deliveries']</code>.</td>
<td><code>false</code></td>
</tr>
</tbody>
</table>
<h3 id="action-pack">Action Pack</h3>
<p>Most of the time, Action Pack is set up as part of Rails, but it can be activated separately:</p>
<div class="sourceCode" id="cb19"><pre class="sourceCode ruby"><code class="sourceCode ruby"><span id="cb19-1"><a href="#cb19-1" aria-hidden="true"></a>require <span class="st">'actionpack'</span></span>
<span id="cb19-2"><a href="#cb19-2" aria-hidden="true"></a>require <span class="st">'ddtrace'</span></span>
<span id="cb19-3"><a href="#cb19-3" aria-hidden="true"></a></span>
<span id="cb19-4"><a href="#cb19-4" aria-hidden="true"></a><span class="dt">Datadog</span>.configure <span class="kw">do</span> |c|</span>
<span id="cb19-5"><a href="#cb19-5" aria-hidden="true"></a> c.tracing.instrument <span class="st">:action_pack</span></span>
<span id="cb19-6"><a href="#cb19-6" aria-hidden="true"></a><span class="kw">end</span></span></code></pre></div>
<h3 id="action-view">Action View</h3>
<p>Most of the time, Action View is set up as part of Rails, but it can be activated separately:</p>
<div class="sourceCode" id="cb20"><pre class="sourceCode ruby"><code class="sourceCode ruby"><span id="cb20-1"><a href="#cb20-1" aria-hidden="true"></a>require <span class="st">'actionview'</span></span>
<span id="cb20-2"><a href="#cb20-2" aria-hidden="true"></a>require <span class="st">'ddtrace'</span></span>
<span id="cb20-3"><a href="#cb20-3" aria-hidden="true"></a></span>
<span id="cb20-4"><a href="#cb20-4" aria-hidden="true"></a><span class="dt">Datadog</span>.configure <span class="kw">do</span> |c|</span>
<span id="cb20-5"><a href="#cb20-5" aria-hidden="true"></a> c.tracing.instrument <span class="st">:action_view</span>, **options</span>
<span id="cb20-6"><a href="#cb20-6" aria-hidden="true"></a><span class="kw">end</span></span></code></pre></div>
<p><code>options</code> are the following keyword arguments:</p>
<table>
<colgroup>
<col style="width: 33%">
<col style="width: 33%">
<col style="width: 33%">
</colgroup>
<thead>
<tr class="header">
<th>Key</th>
<th>Description</th>
<th>Default</th>
</tr>
</thead>
<tbody>
<tr class="odd">
<td><code>template_base_path</code></td>
<td>Used when the template name is parsed. If you don’t store your templates in the <code>views/</code> folder, you may need to change this value</td>
<td><code>'views/'</code></td>
</tr>
</tbody>
</table>
<h3 id="active-job">Active Job</h3>
<p>Most of the time, Active Job is set up as part of Rails, but it can be activated separately:</p>
<div class="sourceCode" id="cb21"><pre class="sourceCode ruby"><code class="sourceCode ruby"><span id="cb21-1"><a href="#cb21-1" aria-hidden="true"></a>require <span class="st">'active_job'</span></span>
<span id="cb21-2"><a href="#cb21-2" aria-hidden="true"></a>require <span class="st">'ddtrace'</span></span>
<span id="cb21-3"><a href="#cb21-3" aria-hidden="true"></a></span>
<span id="cb21-4"><a href="#cb21-4" aria-hidden="true"></a><span class="dt">Datadog</span>.configure <span class="kw">do</span> |c|</span>
<span id="cb21-5"><a href="#cb21-5" aria-hidden="true"></a> c.tracing.instrument <span class="st">:active_job</span></span>
<span id="cb21-6"><a href="#cb21-6" aria-hidden="true"></a><span class="kw">end</span></span>
<span id="cb21-7"><a href="#cb21-7" aria-hidden="true"></a></span>
<span id="cb21-8"><a href="#cb21-8" aria-hidden="true"></a><span class="dt">ExampleJob</span>.perform_later</span></code></pre></div>
<h3 id="active-model-serializers">Active Model Serializers</h3>
<p>The Active Model Serializers integration traces the <code>serialize</code> event for version 0.9+ and the <code>render</code> event for version 0.10+.</p>
<div class="sourceCode" id="cb22"><pre class="sourceCode ruby"><code class="sourceCode ruby"><span id="cb22-1"><a href="#cb22-1" aria-hidden="true"></a>require <span class="st">'active_model_serializers'</span></span>
<span id="cb22-2"><a href="#cb22-2" aria-hidden="true"></a>require <span class="st">'ddtrace'</span></span>
<span id="cb22-3"><a href="#cb22-3" aria-hidden="true"></a></span>
<span id="cb22-4"><a href="#cb22-4" aria-hidden="true"></a><span class="dt">Datadog</span>.configure <span class="kw">do</span> |c|</span>
<span id="cb22-5"><a href="#cb22-5" aria-hidden="true"></a> c.tracing.instrument <span class="st">:active_model_serializers</span></span>
<span id="cb22-6"><a href="#cb22-6" aria-hidden="true"></a><span class="kw">end</span></span>
<span id="cb22-7"><a href="#cb22-7" aria-hidden="true"></a></span>
<span id="cb22-8"><a href="#cb22-8" aria-hidden="true"></a>my_object = <span class="dt">MyModel</span>.new(<span class="st">name: 'my object'</span>)</span>
<span id="cb22-9"><a href="#cb22-9" aria-hidden="true"></a><span class="dt">ActiveModelSerializers</span>::<span class="dt">SerializableResource</span>.new(test_obj).serializable_hash</span></code></pre></div>
<h3 id="active-record">Active Record</h3>
<p>Most of the time, Active Record is set up as part of a web framework (Rails, Sinatra…) however, it can be set up alone:</p>
<div class="sourceCode" id="cb23"><pre class="sourceCode ruby"><code class="sourceCode ruby"><span id="cb23-1"><a href="#cb23-1" aria-hidden="true"></a>require <span class="st">'tmpdir'</span></span>
<span id="cb23-2"><a href="#cb23-2" aria-hidden="true"></a>require <span class="st">'sqlite3'</span></span>
<span id="cb23-3"><a href="#cb23-3" aria-hidden="true"></a>require <span class="st">'active_record'</span></span>
<span id="cb23-4"><a href="#cb23-4" aria-hidden="true"></a>require <span class="st">'ddtrace'</span></span>
<span id="cb23-5"><a href="#cb23-5" aria-hidden="true"></a></span>
<span id="cb23-6"><a href="#cb23-6" aria-hidden="true"></a><span class="dt">Datadog</span>.configure <span class="kw">do</span> |c|</span>
<span id="cb23-7"><a href="#cb23-7" aria-hidden="true"></a> c.tracing.instrument <span class="st">:active_record</span>, **options</span>
<span id="cb23-8"><a href="#cb23-8" aria-hidden="true"></a><span class="kw">end</span></span>
<span id="cb23-9"><a href="#cb23-9" aria-hidden="true"></a></span>
<span id="cb23-10"><a href="#cb23-10" aria-hidden="true"></a><span class="dt">Dir</span>::<span class="dt">Tmpname</span>.create([<span class="st">'test'</span>, <span class="st">'.sqlite'</span>]) <span class="kw">do</span> |db|</span>
<span id="cb23-11"><a href="#cb23-11" aria-hidden="true"></a> conn = <span class="dt">ActiveRecord</span>::<span class="dt">Base</span>.establish_connection(<span class="st">adapter: 'sqlite3'</span>,</span>
<span id="cb23-12"><a href="#cb23-12" aria-hidden="true"></a> <span class="st">database: </span>db)</span>
<span id="cb23-13"><a href="#cb23-13" aria-hidden="true"></a> conn.connection.execute(<span class="st">'SELECT 42'</span>) <span class="co"># traced!</span></span>
<span id="cb23-14"><a href="#cb23-14" aria-hidden="true"></a><span class="kw">end</span></span></code></pre></div>
<p><code>options</code> are the following keyword arguments:</p>
<table>
<colgroup>
<col style="width: 6%">
<col style="width: 76%">
<col style="width: 17%">
</colgroup>
<thead>
<tr class="header">
<th>Key</th>
<th>Description</th>
<th>Default</th>
</tr>
</thead>
<tbody>
<tr class="odd">
<td><code>service_name</code></td>
<td>Override the service name for the SQL query instrumentation. ActiveRecord instantiation instrumentation always uses the application’s configured service name.</td>
<td>Name of database adapter (e.g. <code>'mysql2'</code>)</td>
</tr>
</tbody>
</table>
<p><strong>Configuring trace settings per database</strong></p>
<p>You can configure trace settings per database connection by using the <code>describes</code> option:</p>
<div class="sourceCode" id="cb24"><pre class="sourceCode ruby"><code class="sourceCode ruby"><span id="cb24-1"><a href="#cb24-1" aria-hidden="true"></a><span class="co"># Provide a `:describes` option with a connection key.</span></span>
<span id="cb24-2"><a href="#cb24-2" aria-hidden="true"></a><span class="co"># Any of the following keys are acceptable and equivalent to one another.</span></span>
<span id="cb24-3"><a href="#cb24-3" aria-hidden="true"></a><span class="co"># If a block is provided, it yields a Settings object that</span></span>
<span id="cb24-4"><a href="#cb24-4" aria-hidden="true"></a><span class="co"># accepts any of the configuration options listed above.</span></span>
<span id="cb24-5"><a href="#cb24-5" aria-hidden="true"></a></span>
<span id="cb24-6"><a href="#cb24-6" aria-hidden="true"></a><span class="dt">Datadog</span>.configure <span class="kw">do</span> |c|</span>
<span id="cb24-7"><a href="#cb24-7" aria-hidden="true"></a> <span class="co"># Symbol matching your database connection in config/database.yml</span></span>
<span id="cb24-8"><a href="#cb24-8" aria-hidden="true"></a> <span class="co"># Only available if you are using Rails with ActiveRecord.</span></span>
<span id="cb24-9"><a href="#cb24-9" aria-hidden="true"></a> c.tracing.instrument <span class="st">:active_record</span>, <span class="st">describes: :secondary_database</span>, <span class="st">service_name: 'secondary-db'</span></span>
<span id="cb24-10"><a href="#cb24-10" aria-hidden="true"></a></span>
<span id="cb24-11"><a href="#cb24-11" aria-hidden="true"></a> <span class="co"># Block configuration pattern.</span></span>
<span id="cb24-12"><a href="#cb24-12" aria-hidden="true"></a> c.tracing.instrument <span class="st">:active_record</span>, <span class="st">describes: :secondary_database</span> <span class="kw">do</span> |second_db|</span>
<span id="cb24-13"><a href="#cb24-13" aria-hidden="true"></a> second_db.service_name = <span class="st">'secondary-db'</span></span>
<span id="cb24-14"><a href="#cb24-14" aria-hidden="true"></a> <span class="kw">end</span></span>
<span id="cb24-15"><a href="#cb24-15" aria-hidden="true"></a></span>
<span id="cb24-16"><a href="#cb24-16" aria-hidden="true"></a> <span class="co"># Connection string with the following connection settings:</span></span>
<span id="cb24-17"><a href="#cb24-17" aria-hidden="true"></a> <span class="co"># adapter, username, host, port, database</span></span>
<span id="cb24-18"><a href="#cb24-18" aria-hidden="true"></a> <span class="co"># Other fields are ignored.</span></span>
<span id="cb24-19"><a href="#cb24-19" aria-hidden="true"></a> c.tracing.instrument <span class="st">:active_record</span>, <span class="st">describes: 'mysql2://[email protected]:3306/mysql'</span>, <span class="st">service_name: 'secondary-db'</span></span>
<span id="cb24-20"><a href="#cb24-20" aria-hidden="true"></a></span>
<span id="cb24-21"><a href="#cb24-21" aria-hidden="true"></a> <span class="co"># Hash with following connection settings:</span></span>
<span id="cb24-22"><a href="#cb24-22" aria-hidden="true"></a> <span class="co"># adapter, username, host, port, database</span></span>
<span id="cb24-23"><a href="#cb24-23" aria-hidden="true"></a> <span class="co"># Other fields are ignored.</span></span>
<span id="cb24-24"><a href="#cb24-24" aria-hidden="true"></a> c.tracing.instrument <span class="st">:active_record</span>, <span class="st">describes: </span>{</span>
<span id="cb24-25"><a href="#cb24-25" aria-hidden="true"></a> <span class="st">adapter: </span> <span class="st">'mysql2'</span>,</span>
<span id="cb24-26"><a href="#cb24-26" aria-hidden="true"></a> <span class="st">host: </span> <span class="st">'127.0.0.1'</span>,</span>
<span id="cb24-27"><a href="#cb24-27" aria-hidden="true"></a> <span class="st">port: </span> <span class="st">'3306'</span>,</span>
<span id="cb24-28"><a href="#cb24-28" aria-hidden="true"></a> <span class="st">database: 'mysql'</span>,</span>
<span id="cb24-29"><a href="#cb24-29" aria-hidden="true"></a> <span class="st">username: 'root'</span></span>
<span id="cb24-30"><a href="#cb24-30" aria-hidden="true"></a> },</span>
<span id="cb24-31"><a href="#cb24-31" aria-hidden="true"></a> <span class="st">service_name: 'secondary-db'</span></span>
<span id="cb24-32"><a href="#cb24-32" aria-hidden="true"></a></span>
<span id="cb24-33"><a href="#cb24-33" aria-hidden="true"></a> <span class="co"># If using the `makara` gem, it's possible to match on connection `role`:</span></span>
<span id="cb24-34"><a href="#cb24-34" aria-hidden="true"></a> c.tracing.instrument <span class="st">:active_record</span>, <span class="st">describes: </span>{ <span class="st">makara_role: 'primary'</span> }, <span class="st">service_name: 'primary-db'</span></span>
<span id="cb24-35"><a href="#cb24-35" aria-hidden="true"></a> c.tracing.instrument <span class="st">:active_record</span>, <span class="st">describes: </span>{ <span class="st">makara_role: 'replica'</span> }, <span class="st">service_name: 'secondary-db'</span></span>
<span id="cb24-36"><a href="#cb24-36" aria-hidden="true"></a><span class="kw">end</span></span></code></pre></div>
<p>You can also create configurations based on partial matching of database connection fields:</p>
<div class="sourceCode" id="cb25"><pre class="sourceCode ruby"><code class="sourceCode ruby"><span id="cb25-1"><a href="#cb25-1" aria-hidden="true"></a><span class="dt">Datadog</span>.configure <span class="kw">do</span> |c|</span>
<span id="cb25-2"><a href="#cb25-2" aria-hidden="true"></a> <span class="co"># Matches any connection on host `127.0.0.1`.</span></span>
<span id="cb25-3"><a href="#cb25-3" aria-hidden="true"></a> c.tracing.instrument <span class="st">:active_record</span>, <span class="st">describes: </span>{ <span class="st">host: </span> <span class="st">'127.0.0.1'</span> }, <span class="st">service_name: 'local-db'</span></span>
<span id="cb25-4"><a href="#cb25-4" aria-hidden="true"></a></span>
<span id="cb25-5"><a href="#cb25-5" aria-hidden="true"></a> <span class="co"># Matches any `mysql2` connection.</span></span>
<span id="cb25-6"><a href="#cb25-6" aria-hidden="true"></a> c.tracing.instrument <span class="st">:active_record</span>, <span class="st">describes: </span>{ <span class="st">adapter: 'mysql2'</span>}, <span class="st">service_name: 'mysql-db'</span></span>
<span id="cb25-7"><a href="#cb25-7" aria-hidden="true"></a></span>
<span id="cb25-8"><a href="#cb25-8" aria-hidden="true"></a> <span class="co"># Matches any `mysql2` connection to the `reports` database.</span></span>
<span id="cb25-9"><a href="#cb25-9" aria-hidden="true"></a> <span class="co">#</span></span>
<span id="cb25-10"><a href="#cb25-10" aria-hidden="true"></a> <span class="co"># In case of multiple matching `describe` configurations, the latest one applies.</span></span>
<span id="cb25-11"><a href="#cb25-11" aria-hidden="true"></a> <span class="co"># In this case a connection with both adapter `mysql` and database `reports`</span></span>
<span id="cb25-12"><a href="#cb25-12" aria-hidden="true"></a> <span class="co"># will be configured `service_name: 'reports-db'`, not `service_name: 'mysql-db'`.</span></span>
<span id="cb25-13"><a href="#cb25-13" aria-hidden="true"></a> c.tracing.instrument <span class="st">:active_record</span>, <span class="st">describes: </span>{ <span class="st">adapter: 'mysql2'</span>, <span class="st">database: </span> <span class="st">'reports'</span>}, <span class="st">service_name: 'reports-db'</span></span>
<span id="cb25-14"><a href="#cb25-14" aria-hidden="true"></a><span class="kw">end</span></span></code></pre></div>
<p>When multiple <code>describes</code> configurations match a connection, the latest configured rule that matches will be applied.</p>
<p>If ActiveRecord traces an event that uses a connection that matches a key defined by <code>describes</code>, it will use the trace settings assigned to that connection. If the connection does not match any of the described connections, it will use default settings defined by <code>c.tracing.instrument :active_record</code> instead.</p>
<h3 id="active-support">Active Support</h3>
<p>Most of the time, Active Support is set up as part of Rails, but it can be activated separately:</p>
<div class="sourceCode" id="cb26"><pre class="sourceCode ruby"><code class="sourceCode ruby"><span id="cb26-1"><a href="#cb26-1" aria-hidden="true"></a>require <span class="st">'activesupport'</span></span>
<span id="cb26-2"><a href="#cb26-2" aria-hidden="true"></a>require <span class="st">'ddtrace'</span></span>
<span id="cb26-3"><a href="#cb26-3" aria-hidden="true"></a></span>
<span id="cb26-4"><a href="#cb26-4" aria-hidden="true"></a><span class="dt">Datadog</span>.configure <span class="kw">do</span> |c|</span>
<span id="cb26-5"><a href="#cb26-5" aria-hidden="true"></a> c.tracing.instrument <span class="st">:active_support</span>, **options</span>
<span id="cb26-6"><a href="#cb26-6" aria-hidden="true"></a><span class="kw">end</span></span>
<span id="cb26-7"><a href="#cb26-7" aria-hidden="true"></a></span>
<span id="cb26-8"><a href="#cb26-8" aria-hidden="true"></a>cache = <span class="dt">ActiveSupport</span>::<span class="dt">Cache</span>::<span class="dt">MemoryStore</span>.new</span>
<span id="cb26-9"><a href="#cb26-9" aria-hidden="true"></a>cache.read(<span class="st">'city'</span>)</span></code></pre></div>
<p><code>options</code> are the following keyword arguments:</p>
<table>
<colgroup>
<col style="width: 7%">
<col style="width: 82%">
<col style="width: 10%">
</colgroup>
<thead>
<tr class="header">
<th>Key</th>
<th>Description</th>
<th>Default</th>
</tr>
</thead>
<tbody>
<tr class="odd">
<td><code>cache_service</code></td>
<td>Name of application running the <code>active_support</code> instrumentation. May be overridden by <code>global_default_service_name</code>. <a href="#additional-configuration">See <em>Additional Configuration</em> for more details</a>
</td>
<td><code>active_support-cache</code></td>
</tr>
</tbody>
</table>
<h3 id="aws">AWS</h3>
<p>The AWS integration will trace every interaction (e.g. API calls) with AWS services (S3, ElastiCache etc.).</p>
<div class="sourceCode" id="cb27"><pre class="sourceCode ruby"><code class="sourceCode ruby"><span id="cb27-1"><a href="#cb27-1" aria-hidden="true"></a>require <span class="st">'aws-sdk'</span></span>
<span id="cb27-2"><a href="#cb27-2" aria-hidden="true"></a>require <span class="st">'ddtrace'</span></span>
<span id="cb27-3"><a href="#cb27-3" aria-hidden="true"></a></span>
<span id="cb27-4"><a href="#cb27-4" aria-hidden="true"></a><span class="dt">Datadog</span>.configure <span class="kw">do</span> |c|</span>
<span id="cb27-5"><a href="#cb27-5" aria-hidden="true"></a> c.tracing.instrument <span class="st">:aws</span>, **options</span>
<span id="cb27-6"><a href="#cb27-6" aria-hidden="true"></a><span class="kw">end</span></span>
<span id="cb27-7"><a href="#cb27-7" aria-hidden="true"></a></span>
<span id="cb27-8"><a href="#cb27-8" aria-hidden="true"></a><span class="co"># Perform traced call</span></span>
<span id="cb27-9"><a href="#cb27-9" aria-hidden="true"></a><span class="dt">Aws</span>::<span class="dt">S3</span>::<span class="dt">Client</span>.new.list_buckets</span></code></pre></div>
<p><code>options</code> are the following keyword arguments:</p>
<table>
<colgroup>
<col style="width: 6%">
<col style="width: 12%">
<col style="width: 77%">
<col style="width: 3%">
</colgroup>
<thead>
<tr class="header">
<th>Key</th>
<th>Env Var</th>
<th>Description</th>
<th>Default</th>
</tr>
</thead>
<tbody>
<tr class="odd">
<td><code>service_name</code></td>
<td><code>DD_TRACE_AWS_SERVICE_NAME</code></td>
<td>Name of application running the <code>aws</code> instrumentation. May be overridden by <code>global_default_service_name</code>. <a href="#additional-configuration">See <em>Additional Configuration</em> for more details</a>
</td>
<td><code>aws</code></td>
</tr>
<tr class="even">
<td><code>peer_service</code></td>
<td><code>DD_TRACE_AWS_PEER_SERVICE</code></td>
<td>Name of external service the application connects to</td>
<td><code>nil</code></td>
</tr>
</tbody>
</table>
<h3 id="concurrent-ruby">Concurrent Ruby</h3>
<p>The Concurrent Ruby integration adds support for context propagation when using <code>::Concurrent::Future</code>. Making sure that code traced within the <code>Future#execute</code> will have correct parent set.</p>
<p>To activate your integration, use the <code>Datadog.configure</code> method:</p>
<div class="sourceCode" id="cb28"><pre class="sourceCode ruby"><code class="sourceCode ruby"><span id="cb28-1"><a href="#cb28-1" aria-hidden="true"></a><span class="co"># Inside Rails initializer or equivalent</span></span>
<span id="cb28-2"><a href="#cb28-2" aria-hidden="true"></a><span class="dt">Datadog</span>.configure <span class="kw">do</span> |c|</span>
<span id="cb28-3"><a href="#cb28-3" aria-hidden="true"></a> <span class="co"># Patches ::Concurrent::Future to use ExecutorService that propagates context</span></span>
<span id="cb28-4"><a href="#cb28-4" aria-hidden="true"></a> c.tracing.instrument <span class="st">:concurrent_ruby</span></span>
<span id="cb28-5"><a href="#cb28-5" aria-hidden="true"></a><span class="kw">end</span></span>
<span id="cb28-6"><a href="#cb28-6" aria-hidden="true"></a></span>
<span id="cb28-7"><a href="#cb28-7" aria-hidden="true"></a><span class="co"># Pass context into code executed within Concurrent::Future</span></span>
<span id="cb28-8"><a href="#cb28-8" aria-hidden="true"></a><span class="dt">Datadog</span>::<span class="dt">Tracing</span>.trace(<span class="st">'outer'</span>) <span class="kw">do</span></span>
<span id="cb28-9"><a href="#cb28-9" aria-hidden="true"></a> <span class="dt">Concurrent</span>::<span class="dt">Future</span>.execute { <span class="dt">Datadog</span>::<span class="dt">Tracing</span>.trace(<span class="st">'inner'</span>) { } }.wait</span>
<span id="cb28-10"><a href="#cb28-10" aria-hidden="true"></a><span class="kw">end</span></span></code></pre></div>
<h3 id="cucumber">Cucumber</h3>
<p>Cucumber integration will trace all executions of scenarios and steps when using <code>cucumber</code> framework.</p>
<p>To activate your integration, use the <code>Datadog.configure</code> method:</p>
<div class="sourceCode" id="cb29"><pre class="sourceCode ruby"><code class="sourceCode ruby"><span id="cb29-1"><a href="#cb29-1" aria-hidden="true"></a>require <span class="st">'cucumber'</span></span>
<span id="cb29-2"><a href="#cb29-2" aria-hidden="true"></a>require <span class="st">'ddtrace'</span></span>
<span id="cb29-3"><a href="#cb29-3" aria-hidden="true"></a></span>
<span id="cb29-4"><a href="#cb29-4" aria-hidden="true"></a><span class="co"># Configure default Cucumber integration</span></span>
<span id="cb29-5"><a href="#cb29-5" aria-hidden="true"></a><span class="dt">Datadog</span>.configure <span class="kw">do</span> |c|</span>
<span id="cb29-6"><a href="#cb29-6" aria-hidden="true"></a> c.ci.instrument <span class="st">:cucumber</span>, **options</span>
<span id="cb29-7"><a href="#cb29-7" aria-hidden="true"></a><span class="kw">end</span></span>
<span id="cb29-8"><a href="#cb29-8" aria-hidden="true"></a></span>
<span id="cb29-9"><a href="#cb29-9" aria-hidden="true"></a><span class="co"># Example of how to attach tags from scenario to active span</span></span>
<span id="cb29-10"><a href="#cb29-10" aria-hidden="true"></a><span class="dt">Around</span> <span class="kw">do</span> |scenario, block|</span>
<span id="cb29-11"><a href="#cb29-11" aria-hidden="true"></a> active_span = <span class="dt">Datadog</span>.configuration[<span class="st">:cucumber</span>][<span class="st">:tracer</span>].active_span</span>
<span id="cb29-12"><a href="#cb29-12" aria-hidden="true"></a> <span class="kw">unless</span> active_span.nil?</span>
<span id="cb29-13"><a href="#cb29-13" aria-hidden="true"></a> scenario.tags.filter { |tag| tag.include? <span class="ch">':'</span> }.each <span class="kw">do</span> |tag|</span>
<span id="cb29-14"><a href="#cb29-14" aria-hidden="true"></a> active_span.set_tag(*tag.name.split(<span class="ch">':'</span>, <span class="dv">2</span>))</span>
<span id="cb29-15"><a href="#cb29-15" aria-hidden="true"></a> <span class="kw">end</span></span>
<span id="cb29-16"><a href="#cb29-16" aria-hidden="true"></a> <span class="kw">end</span></span>
<span id="cb29-17"><a href="#cb29-17" aria-hidden="true"></a> block.call</span>
<span id="cb29-18"><a href="#cb29-18" aria-hidden="true"></a><span class="kw">end</span></span></code></pre></div>
<p><code>options</code> are the following keyword arguments:</p>
<table>
<colgroup>
<col style="width: 14%">
<col style="width: 52%">
<col style="width: 33%">
</colgroup>
<thead>
<tr class="header">
<th>Key</th>
<th>Description</th>
<th>Default</th>
</tr>
</thead>
<tbody>
<tr class="odd">
<td><code>enabled</code></td>
<td>Defines whether Cucumber tests should be traced. Useful for temporarily disabling tracing. <code>true</code> or <code>false</code>
</td>
<td><code>true</code></td>
</tr>
<tr class="even">
<td><code>service_name</code></td>
<td>Service name used for <code>cucumber</code> instrumentation.</td>
<td><code>'cucumber'</code></td>
</tr>
<tr class="odd">
<td><code>operation_name</code></td>
<td>Operation name used for <code>cucumber</code> instrumentation. Useful if you want rename automatic trace metrics e.g. <code>trace.#{operation_name}.errors</code>.</td>
<td><code>'cucumber.test'</code></td>
</tr>
</tbody>
</table>
<h3 id="dalli">Dalli</h3>
<p>Dalli integration will trace all calls to your <code>memcached</code> server:</p>
<div class="sourceCode" id="cb30"><pre class="sourceCode ruby"><code class="sourceCode ruby"><span id="cb30-1"><a href="#cb30-1" aria-hidden="true"></a>require <span class="st">'dalli'</span></span>
<span id="cb30-2"><a href="#cb30-2" aria-hidden="true"></a>require <span class="st">'ddtrace'</span></span>
<span id="cb30-3"><a href="#cb30-3" aria-hidden="true"></a></span>
<span id="cb30-4"><a href="#cb30-4" aria-hidden="true"></a><span class="co"># Configure default Dalli tracing behavior</span></span>
<span id="cb30-5"><a href="#cb30-5" aria-hidden="true"></a><span class="dt">Datadog</span>.configure <span class="kw">do</span> |c|</span>
<span id="cb30-6"><a href="#cb30-6" aria-hidden="true"></a> c.tracing.instrument <span class="st">:dalli</span>, **options</span>
<span id="cb30-7"><a href="#cb30-7" aria-hidden="true"></a><span class="kw">end</span></span>
<span id="cb30-8"><a href="#cb30-8" aria-hidden="true"></a></span>
<span id="cb30-9"><a href="#cb30-9" aria-hidden="true"></a><span class="co"># Configure Dalli tracing behavior for single client</span></span>
<span id="cb30-10"><a href="#cb30-10" aria-hidden="true"></a>client = <span class="dt">Dalli</span>::<span class="dt">Client</span>.new(<span class="st">'localhost:11211'</span>, **options)</span>
<span id="cb30-11"><a href="#cb30-11" aria-hidden="true"></a>client.set(<span class="st">'abc'</span>, <span class="dv">123</span>)</span></code></pre></div>
<p><code>options</code> are the following keyword arguments:</p>
<table>
<colgroup>
<col style="width: 6%">
<col style="width: 12%">
<col style="width: 75%">
<col style="width: 5%">
</colgroup>
<thead>
<tr class="header">
<th>Key</th>
<th>Env Var</th>
<th>Description</th>
<th>Default</th>
</tr>
</thead>
<tbody>
<tr class="odd">
<td><code>command_enabled</code></td>
<td><code>DD_TRACE_MEMCACHED_COMMAND_ENABLED</code></td>
<td>Collect commands as the <code>memcached.command</code> tag. Command <code>keys</code> can potentially contain sensitive information.</td>
<td><code>false</code></td>
</tr>
<tr class="even">
<td><code>service_name</code></td>
<td><code>DD_TRACE_DALLI_SERVICE_NAME</code></td>
<td>Name of application running the <code>dalli</code> instrumentation. May be overridden by <code>global_default_service_name</code>. <a href="#additional-configuration">See <em>Additional Configuration</em> for more details</a>
</td>
<td><code>memcached</code></td>
</tr>
<tr class="odd">
<td><code>peer_service</code></td>
<td><code>DD_TRACE_DALLI_PEER_SERVICE</code></td>
<td>Name of external service the application connects to</td>
<td><code>nil</code></td>
</tr>
</tbody>
</table>
<h3 id="delayedjob">DelayedJob</h3>
<p>The DelayedJob integration uses lifecycle hooks to trace the job executions and enqueues.</p>
<p>You can enable it through <code>Datadog.configure</code>:</p>
<div class="sourceCode" id="cb31"><pre class="sourceCode ruby"><code class="sourceCode ruby"><span id="cb31-1"><a href="#cb31-1" aria-hidden="true"></a>require <span class="st">'ddtrace'</span></span>
<span id="cb31-2"><a href="#cb31-2" aria-hidden="true"></a></span>
<span id="cb31-3"><a href="#cb31-3" aria-hidden="true"></a><span class="dt">Datadog</span>.configure <span class="kw">do</span> |c|</span>
<span id="cb31-4"><a href="#cb31-4" aria-hidden="true"></a> c.tracing.instrument <span class="st">:delayed_job</span>, **options</span>
<span id="cb31-5"><a href="#cb31-5" aria-hidden="true"></a><span class="kw">end</span></span></code></pre></div>
<p><code>options</code> are the following keyword arguments:</p>
<table>
<colgroup>
<col style="width: 14%">
<col style="width: 52%">
<col style="width: 33%">
</colgroup>
<thead>
<tr class="header">
<th>Key</th>
<th>Description</th>
<th>Default</th>
</tr>
</thead>
<tbody>
<tr class="odd">
<td><code>error_handler</code></td>
<td>Custom error handler invoked when a job raises an error. Provided <code>span</code> and <code>error</code> as arguments. Sets error on the span by default. Useful for ignoring transient errors.</td>
<td><code>proc { \|span, error\| span.set_error(error) unless span.nil? }</code></td>
</tr>
</tbody>
</table>
<h3 id="elasticsearch">Elasticsearch</h3>
<p>The Elasticsearch integration will trace any call to <code>perform_request</code> in the <code>Client</code> object:</p>
<div class="sourceCode" id="cb32"><pre class="sourceCode ruby"><code class="sourceCode ruby"><span id="cb32-1"><a href="#cb32-1" aria-hidden="true"></a>require <span class="st">'elasticsearch/transport'</span></span>
<span id="cb32-2"><a href="#cb32-2" aria-hidden="true"></a>require <span class="st">'ddtrace'</span></span>
<span id="cb32-3"><a href="#cb32-3" aria-hidden="true"></a></span>
<span id="cb32-4"><a href="#cb32-4" aria-hidden="true"></a><span class="dt">Datadog</span>.configure <span class="kw">do</span> |c|</span>
<span id="cb32-5"><a href="#cb32-5" aria-hidden="true"></a> c.tracing.instrument <span class="st">:elasticsearch</span>, **options</span>
<span id="cb32-6"><a href="#cb32-6" aria-hidden="true"></a><span class="kw">end</span></span>
<span id="cb32-7"><a href="#cb32-7" aria-hidden="true"></a></span>
<span id="cb32-8"><a href="#cb32-8" aria-hidden="true"></a><span class="co"># Perform a query to Elasticsearch</span></span>
<span id="cb32-9"><a href="#cb32-9" aria-hidden="true"></a>client = <span class="dt">Elasticsearch</span>::<span class="dt">Client</span>.new <span class="st">url: 'http://127.0.0.1:9200'</span></span>
<span id="cb32-10"><a href="#cb32-10" aria-hidden="true"></a>response = client.perform_request <span class="st">'GET'</span>, <span class="st">'_cluster/health'</span></span>
<span id="cb32-11"><a href="#cb32-11" aria-hidden="true"></a></span>
<span id="cb32-12"><a href="#cb32-12" aria-hidden="true"></a><span class="co"># In case you want to override the global configuration for a certain client instance</span></span>
<span id="cb32-13"><a href="#cb32-13" aria-hidden="true"></a><span class="dt">Datadog</span>.configure_onto(client.transport, **options)</span></code></pre></div>
<p><code>options</code> are the following keyword arguments:</p>
<table>
<colgroup>
<col style="width: 5%">
<col style="width: 14%">
<col style="width: 73%">