GettingStarted.html

<!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=&lt;port&gt;</code> in the Agent’s environment</li>
</ul>
<p>OR</p>
<ul>
<li>Add <code>apm_config: receiver_port: &lt;port&gt;</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=&lt;path-to-socket-file&gt;</code>
</li>
</ul>
<p>OR</p>
<ul>
<li>Add <code>apm_config: receiver_socket: &lt;path-to-socket-file&gt;</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://root@127.0.0.1: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%">
<col style="width: 6%">
</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_ELASTICSEARCH_SERVICE_NAME</code></td>
<td>Name of application running the <code>elasticsearch</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>elasticsearch</code></td>
</tr>
<tr class="even">
<td><code>peer_service</code></td>
<td><code>DD_TRACE_ELASTICSEARCH_PEER_SERVICE</code></td>
<td>Name of external service the application connects to</td>
<td><code>nil</code></td>
</tr>
<tr class="odd">
<td><code>quantize</code></td>
<td></td>
<td>Hash containing options for quantization. May include <code>:show</code> with an Array of keys to not quantize (or <code>:all</code> to skip quantization), or <code>:exclude</code> with Array of keys to exclude entirely.</td>
<td><code>{}</code></td>
</tr>
</tbody>
</table>
<h3 id="ethon">Ethon</h3>
<p>The <code>ethon</code> integration will trace any HTTP request through <code>Easy</code> or <code>Multi</code> objects. Note that this integration also supports <code>Typhoeus</code> library which is based on <code>Ethon</code>.</p>
<div class="sourceCode" id="cb33"><pre class="sourceCode ruby"><code class="sourceCode ruby"><span id="cb33-1"><a href="#cb33-1" aria-hidden="true"></a>require <span class="st">'ddtrace'</span></span>
<span id="cb33-2"><a href="#cb33-2" aria-hidden="true"></a></span>
<span id="cb33-3"><a href="#cb33-3" aria-hidden="true"></a><span class="dt">Datadog</span>.configure <span class="kw">do</span> |c|</span>
<span id="cb33-4"><a href="#cb33-4" aria-hidden="true"></a>  c.tracing.instrument <span class="st">:ethon</span>, **options</span>
<span id="cb33-5"><a href="#cb33-5" aria-hidden="true"></a></span>
<span id="cb33-6"><a href="#cb33-6" aria-hidden="true"></a>  <span class="co"># optionally, specify a different service name for hostnames matching a regex</span></span>
<span id="cb33-7"><a href="#cb33-7" aria-hidden="true"></a>  c.tracing.instrument <span class="st">:ethon</span>, <span class="st">describes: </span><span class="ot">/user-[^.]+\.example\.com/</span> <span class="kw">do</span> |ethon|</span>
<span id="cb33-8"><a href="#cb33-8" aria-hidden="true"></a>    ethon.service_name = <span class="st">'user.example.com'</span></span>
<span id="cb33-9"><a href="#cb33-9" aria-hidden="true"></a>    ethon.split_by_domain = <span class="dv">false</span> <span class="co"># Only necessary if split_by_domain is true by default</span></span>
<span id="cb33-10"><a href="#cb33-10" aria-hidden="true"></a>  <span class="kw">end</span></span>
<span id="cb33-11"><a href="#cb33-11" 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: 9%">
<col style="width: 12%">
<col style="width: 74%">
<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_ETHON_SERVICE_NAME</code></td>
<td>Name of application running the <code>ethon</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>ethon</code></td>
</tr>
<tr class="even">
<td><code>peer_service</code></td>
<td><code>DD_TRACE_ETHON_PEER_SERVICE</code></td>
<td>Name of external service the application connects to</td>
<td><code>nil</code></td>
</tr>
<tr class="odd">
<td><code>distributed_tracing</code></td>
<td></td>
<td>Enables <a href="#distributed-tracing">distributed tracing</a>
</td>
<td><code>true</code></td>
</tr>
<tr class="even">
<td><code>split_by_domain</code></td>
<td></td>
<td>Uses the request domain as the service name when set to <code>true</code>.</td>
<td><code>false</code></td>
</tr>
</tbody>
</table>
<h3 id="excon">Excon</h3>
<p>The <code>excon</code> integration is available through the <code>ddtrace</code> middleware:</p>
<div class="sourceCode" id="cb34"><pre class="sourceCode ruby"><code class="sourceCode ruby"><span id="cb34-1"><a href="#cb34-1" aria-hidden="true"></a>require <span class="st">'excon'</span></span>
<span id="cb34-2"><a href="#cb34-2" aria-hidden="true"></a>require <span class="st">'ddtrace'</span></span>
<span id="cb34-3"><a href="#cb34-3" aria-hidden="true"></a></span>
<span id="cb34-4"><a href="#cb34-4" aria-hidden="true"></a><span class="co"># Configure default Excon tracing behavior</span></span>
<span id="cb34-5"><a href="#cb34-5" aria-hidden="true"></a><span class="dt">Datadog</span>.configure <span class="kw">do</span> |c|</span>
<span id="cb34-6"><a href="#cb34-6" aria-hidden="true"></a>  c.tracing.instrument <span class="st">:excon</span>, **options</span>
<span id="cb34-7"><a href="#cb34-7" aria-hidden="true"></a></span>
<span id="cb34-8"><a href="#cb34-8" aria-hidden="true"></a>  <span class="co"># optionally, specify a different service name for hostnames matching a regex</span></span>
<span id="cb34-9"><a href="#cb34-9" aria-hidden="true"></a>  c.tracing.instrument <span class="st">:excon</span>, <span class="st">describes: </span><span class="ot">/user-[^.]+\.example\.com/</span> <span class="kw">do</span> |excon|</span>
<span id="cb34-10"><a href="#cb34-10" aria-hidden="true"></a>    excon.service_name = <span class="st">'user.example.com'</span></span>
<span id="cb34-11"><a href="#cb34-11" aria-hidden="true"></a>    excon.split_by_domain = <span class="dv">false</span> <span class="co"># Only necessary if split_by_domain is true by default</span></span>
<span id="cb34-12"><a href="#cb34-12" aria-hidden="true"></a>  <span class="kw">end</span></span>
<span id="cb34-13"><a href="#cb34-13" aria-hidden="true"></a><span class="kw">end</span></span>
<span id="cb34-14"><a href="#cb34-14" aria-hidden="true"></a></span>
<span id="cb34-15"><a href="#cb34-15" aria-hidden="true"></a>connection = <span class="dt">Excon</span>.new(<span class="st">'https://example.com'</span>)</span>
<span id="cb34-16"><a href="#cb34-16" aria-hidden="true"></a>connection.get</span></code></pre></div>
<p><code>options</code> are the following keyword arguments:</p>
<table>
<colgroup>
<col style="width: 9%">
<col style="width: 12%">
<col style="width: 74%">
<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_EXCON_SERVICE_NAME</code></td>
<td>Name of application running the <code>excon</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>excon</code></td>
</tr>
<tr class="even">
<td><code>peer_service</code></td>
<td><code>DD_TRACE_EXCON_PEER_SERVICE</code></td>
<td>Name of external service the application connects to</td>
<td><code>nil</code></td>
</tr>
<tr class="odd">
<td><code>distributed_tracing</code></td>
<td></td>
<td>Enables <a href="#distributed-tracing">distributed tracing</a>
</td>
<td><code>true</code></td>
</tr>
<tr class="even">
<td><code>split_by_domain</code></td>
<td></td>
<td>Uses the request domain as the service name when set to <code>true</code>.</td>
<td><code>false</code></td>
</tr>
<tr class="odd">
<td><code>error_handler</code></td>
<td></td>
<td>A <code>Proc</code> that accepts a <code>response</code> parameter. If it evaluates to a <em>truthy</em> value, the trace span is marked as an error. By default only sets 5XX responses as errors.</td>
<td><code>nil</code></td>
</tr>
</tbody>
</table>
<p><strong>Configuring connections to use different settings</strong></p>
<p>If you use multiple connections with Excon, you can give each of them different settings by configuring their constructors with middleware:</p>
<div class="sourceCode" id="cb35"><pre class="sourceCode ruby"><code class="sourceCode ruby"><span id="cb35-1"><a href="#cb35-1" aria-hidden="true"></a><span class="co"># Wrap the Datadog tracing middleware around the default middleware stack</span></span>
<span id="cb35-2"><a href="#cb35-2" aria-hidden="true"></a><span class="dt">Excon</span>.new(</span>
<span id="cb35-3"><a href="#cb35-3" aria-hidden="true"></a>  <span class="st">'http://example.com'</span>,</span>
<span id="cb35-4"><a href="#cb35-4" aria-hidden="true"></a>  <span class="st">middlewares: </span><span class="dt">Datadog</span>::<span class="dt">Tracing</span>::<span class="dt">Contrib</span>::<span class="dt">Excon</span>::<span class="dt">Middleware</span>.with(options).around_default_stack</span>
<span id="cb35-5"><a href="#cb35-5" aria-hidden="true"></a>)</span>
<span id="cb35-6"><a href="#cb35-6" aria-hidden="true"></a></span>
<span id="cb35-7"><a href="#cb35-7" aria-hidden="true"></a><span class="co"># Insert the middleware into a custom middleware stack.</span></span>
<span id="cb35-8"><a href="#cb35-8" aria-hidden="true"></a><span class="co"># </span><span class="al">NOTE</span><span class="co">: Trace middleware must be inserted after ResponseParser!</span></span>
<span id="cb35-9"><a href="#cb35-9" aria-hidden="true"></a><span class="dt">Excon</span>.new(</span>
<span id="cb35-10"><a href="#cb35-10" aria-hidden="true"></a>  <span class="st">'http://example.com'</span>,</span>
<span id="cb35-11"><a href="#cb35-11" aria-hidden="true"></a>  <span class="st">middlewares: </span>[</span>
<span id="cb35-12"><a href="#cb35-12" aria-hidden="true"></a>    <span class="dt">Excon</span>::<span class="dt">Middleware</span>::<span class="dt">ResponseParser</span>,</span>
<span id="cb35-13"><a href="#cb35-13" aria-hidden="true"></a>    <span class="dt">Datadog</span>::<span class="dt">Tracing</span>::<span class="dt">Contrib</span>::<span class="dt">Excon</span>::<span class="dt">Middleware</span>.with(options),</span>
<span id="cb35-14"><a href="#cb35-14" aria-hidden="true"></a>    <span class="dt">Excon</span>::<span class="dt">Middleware</span>::<span class="dt">Idempotent</span></span>
<span id="cb35-15"><a href="#cb35-15" aria-hidden="true"></a>  ]</span>
<span id="cb35-16"><a href="#cb35-16" aria-hidden="true"></a>)</span></code></pre></div>
<p>Where <code>options</code> is a Hash that contains any of the parameters listed in the table above.</p>
<h3 id="faraday">Faraday</h3>
<p>The <code>faraday</code> integration is available through the <code>ddtrace</code> middleware:</p>
<div class="sourceCode" id="cb36"><pre class="sourceCode ruby"><code class="sourceCode ruby"><span id="cb36-1"><a href="#cb36-1" aria-hidden="true"></a>require <span class="st">'faraday'</span></span>
<span id="cb36-2"><a href="#cb36-2" aria-hidden="true"></a>require <span class="st">'ddtrace'</span></span>
<span id="cb36-3"><a href="#cb36-3" aria-hidden="true"></a></span>
<span id="cb36-4"><a href="#cb36-4" aria-hidden="true"></a><span class="co"># Configure default Faraday tracing behavior</span></span>
<span id="cb36-5"><a href="#cb36-5" aria-hidden="true"></a><span class="dt">Datadog</span>.configure <span class="kw">do</span> |c|</span>
<span id="cb36-6"><a href="#cb36-6" aria-hidden="true"></a>  c.tracing.instrument <span class="st">:faraday</span>, **options</span>
<span id="cb36-7"><a href="#cb36-7" aria-hidden="true"></a></span>
<span id="cb36-8"><a href="#cb36-8" aria-hidden="true"></a>  <span class="co"># optionally, specify a different service name for hostnames matching a regex</span></span>
<span id="cb36-9"><a href="#cb36-9" aria-hidden="true"></a>  c.tracing.instrument <span class="st">:faraday</span>, <span class="st">describes: </span><span class="ot">/user-[^.]+\.example\.com/</span> <span class="kw">do</span> |faraday|</span>
<span id="cb36-10"><a href="#cb36-10" aria-hidden="true"></a>    faraday.service_name = <span class="st">'user.example.com'</span></span>
<span id="cb36-11"><a href="#cb36-11" aria-hidden="true"></a>    faraday.split_by_domain = <span class="dv">false</span> <span class="co"># Only necessary if split_by_domain is true by default</span></span>
<span id="cb36-12"><a href="#cb36-12" aria-hidden="true"></a>  <span class="kw">end</span></span>
<span id="cb36-13"><a href="#cb36-13" aria-hidden="true"></a><span class="kw">end</span></span>
<span id="cb36-14"><a href="#cb36-14" aria-hidden="true"></a></span>
<span id="cb36-15"><a href="#cb36-15" 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="cb36-16"><a href="#cb36-16" aria-hidden="true"></a>connection = <span class="dt">Faraday</span>.new(<span class="st">'https://example.com'</span>) <span class="kw">do</span> |builder|</span>
<span id="cb36-17"><a href="#cb36-17" aria-hidden="true"></a>  builder.use(<span class="st">:ddtrace</span>, **options)</span>
<span id="cb36-18"><a href="#cb36-18" aria-hidden="true"></a>  builder.adapter <span class="dt">Faraday</span>.default_adapter</span>
<span id="cb36-19"><a href="#cb36-19" aria-hidden="true"></a><span class="kw">end</span></span>
<span id="cb36-20"><a href="#cb36-20" aria-hidden="true"></a></span>
<span id="cb36-21"><a href="#cb36-21" aria-hidden="true"></a>connection.get(<span class="st">'/foo'</span>)</span></code></pre></div>
<p><code>options</code> are the following keyword arguments:</p>
<table>
<colgroup>
<col style="width: 8%">
<col style="width: 12%">
<col style="width: 73%">
<col style="width: 4%">
</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_FARADAY_SERVICE_NAME</code></td>
<td>Name of application running the <code>faraday</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>faraday</code></td>
</tr>
<tr class="even">
<td><code>peer_service</code></td>
<td><code>DD_TRACE_FARADAY_PEER_SERVICE</code></td>
<td>Name of external service the application connects to</td>
<td><code>nil</code></td>
</tr>
<tr class="odd">
<td><code>distributed_tracing</code></td>
<td></td>
<td>Enables <a href="#distributed-tracing">distributed tracing</a>
</td>
<td><code>true</code></td>
</tr>
<tr class="even">
<td><code>split_by_domain</code></td>
<td></td>
<td>Uses the request domain as the service name when set to <code>true</code>.</td>
<td><code>false</code></td>
</tr>
<tr class="odd">
<td><code>error_handler</code></td>
<td></td>
<td>A <code>Proc</code> that accepts a <code>response</code> parameter. If it evaluates to a <em>truthy</em> value, the trace span is marked as an error. By default only sets 5XX responses as errors.</td>
<td><code>nil</code></td>
</tr>
</tbody>
</table>
<h3 id="grape">Grape</h3>
<p>The Grape integration adds the instrumentation to Grape endpoints and filters. This integration can work side by side with other integrations like Rack and Rails.</p>
<p>To activate your integration, use the <code>Datadog.configure</code> method before defining your Grape application:</p>
<div class="sourceCode" id="cb37"><pre class="sourceCode ruby"><code class="sourceCode ruby"><span id="cb37-1"><a href="#cb37-1" aria-hidden="true"></a><span class="co"># api.rb</span></span>
<span id="cb37-2"><a href="#cb37-2" aria-hidden="true"></a>require <span class="st">'grape'</span></span>
<span id="cb37-3"><a href="#cb37-3" aria-hidden="true"></a>require <span class="st">'ddtrace'</span></span>
<span id="cb37-4"><a href="#cb37-4" aria-hidden="true"></a></span>
<span id="cb37-5"><a href="#cb37-5" aria-hidden="true"></a><span class="dt">Datadog</span>.configure <span class="kw">do</span> |c|</span>
<span id="cb37-6"><a href="#cb37-6" aria-hidden="true"></a>  c.tracing.instrument <span class="st">:grape</span>, **options</span>
<span id="cb37-7"><a href="#cb37-7" aria-hidden="true"></a><span class="kw">end</span></span>
<span id="cb37-8"><a href="#cb37-8" aria-hidden="true"></a></span>
<span id="cb37-9"><a href="#cb37-9" aria-hidden="true"></a><span class="co"># Then define your application</span></span>
<span id="cb37-10"><a href="#cb37-10" aria-hidden="true"></a><span class="kw">class</span> <span class="dt">RackTestingAPI</span> &lt; <span class="dt">Grape</span>::<span class="dt">API</span></span>
<span id="cb37-11"><a href="#cb37-11" aria-hidden="true"></a>  desc <span class="st">'main endpoint'</span></span>
<span id="cb37-12"><a href="#cb37-12" aria-hidden="true"></a>  get <span class="st">:success</span> <span class="kw">do</span></span>
<span id="cb37-13"><a href="#cb37-13" aria-hidden="true"></a>    <span class="st">'Hello world!'</span></span>
<span id="cb37-14"><a href="#cb37-14" aria-hidden="true"></a>  <span class="kw">end</span></span>
<span id="cb37-15"><a href="#cb37-15" 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: 10%">
<col style="width: 14%">
<col style="width: 70%">
<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>enabled</code></td>
<td><code>DD_TRACE_GRAPE_ENABLED</code></td>
<td>Defines whether Grape 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>error_statuses</code></td>
<td></td>
<td>Defines a status code or range of status codes which should be marked as errors. <code>'404,405,500-599'</code> or <code>[404,405,'500-599']</code>
</td>
<td><code>nil</code></td>
</tr>
</tbody>
</table>
<h3 id="graphql">GraphQL</h3>
<p>The GraphQL integration activates instrumentation for GraphQL queries.</p>
<p>To activate your integration, use the <code>Datadog.configure</code> method:</p>
<div class="sourceCode" id="cb38"><pre class="sourceCode ruby"><code class="sourceCode ruby"><span id="cb38-1"><a href="#cb38-1" aria-hidden="true"></a><span class="co"># Inside Rails initializer or equivalent</span></span>
<span id="cb38-2"><a href="#cb38-2" aria-hidden="true"></a><span class="dt">Datadog</span>.configure <span class="kw">do</span> |c|</span>
<span id="cb38-3"><a href="#cb38-3" aria-hidden="true"></a>  c.tracing.instrument <span class="st">:graphql</span>, <span class="st">schemas: </span>[<span class="dt">YourSchema</span>], **options</span>
<span id="cb38-4"><a href="#cb38-4" aria-hidden="true"></a><span class="kw">end</span></span>
<span id="cb38-5"><a href="#cb38-5" aria-hidden="true"></a></span>
<span id="cb38-6"><a href="#cb38-6" aria-hidden="true"></a><span class="co"># Then run a GraphQL query</span></span>
<span id="cb38-7"><a href="#cb38-7" aria-hidden="true"></a><span class="dt">YourSchema</span>.execute(query, <span class="st">variables: </span>{}, <span class="st">context: </span>{}, <span class="st">operation_name: </span><span class="dv">nil</span>)</span></code></pre></div>
<p>The <code>instrument :graphql</code> method accepts the following parameters. Additional options can be substituted in for <code>options</code>:</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>schemas</code></td>
<td>Required. Array of <code>GraphQL::Schema</code> objects which to trace. Tracing will be added to all the schemas listed, using the options provided to this configuration. If you do not provide any, then tracing will not be activated.</td>
<td><code>[]</code></td>
</tr>
<tr class="even">
<td><code>service_name</code></td>
<td>Service name used for graphql instrumentation</td>
<td><code>'ruby-graphql'</code></td>
</tr>
</tbody>
</table>
<p><strong>Manually configuring GraphQL schemas</strong></p>
<p>If you prefer to individually configure the tracer settings for a schema (e.g. you have multiple schemas with different service names), in the schema definition, you can add the following <a href="http://graphql-ruby.org/queries/tracing.html">using the GraphQL API</a>:</p>
<div class="sourceCode" id="cb39"><pre class="sourceCode ruby"><code class="sourceCode ruby"><span id="cb39-1"><a href="#cb39-1" aria-hidden="true"></a><span class="co"># Class-based schema</span></span>
<span id="cb39-2"><a href="#cb39-2" aria-hidden="true"></a><span class="kw">class</span> <span class="dt">YourSchema</span> &lt; <span class="dt">GraphQL</span>::<span class="dt">Schema</span></span>
<span id="cb39-3"><a href="#cb39-3" aria-hidden="true"></a>  use(</span>
<span id="cb39-4"><a href="#cb39-4" aria-hidden="true"></a>    <span class="dt">GraphQL</span>::<span class="dt">Tracing</span>::<span class="dt">DataDogTracing</span>,</span>
<span id="cb39-5"><a href="#cb39-5" aria-hidden="true"></a>    <span class="st">service: 'graphql'</span></span>
<span id="cb39-6"><a href="#cb39-6" aria-hidden="true"></a>  )</span>
<span id="cb39-7"><a href="#cb39-7" aria-hidden="true"></a><span class="kw">end</span></span></code></pre></div>
<div class="sourceCode" id="cb40"><pre class="sourceCode ruby"><code class="sourceCode ruby"><span id="cb40-1"><a href="#cb40-1" aria-hidden="true"></a><span class="co"># .define-style schema</span></span>
<span id="cb40-2"><a href="#cb40-2" aria-hidden="true"></a><span class="dt">YourSchema</span> = <span class="dt">GraphQL</span>::<span class="dt">Schema</span>.define <span class="kw">do</span></span>
<span id="cb40-3"><a href="#cb40-3" aria-hidden="true"></a>  use(</span>
<span id="cb40-4"><a href="#cb40-4" aria-hidden="true"></a>    <span class="dt">GraphQL</span>::<span class="dt">Tracing</span>::<span class="dt">DataDogTracing</span>,</span>
<span id="cb40-5"><a href="#cb40-5" aria-hidden="true"></a>    <span class="st">service: 'graphql'</span></span>
<span id="cb40-6"><a href="#cb40-6" aria-hidden="true"></a>  )</span>
<span id="cb40-7"><a href="#cb40-7" aria-hidden="true"></a><span class="kw">end</span></span></code></pre></div>
<p>Or you can modify an already defined schema:</p>
<div class="sourceCode" id="cb41"><pre class="sourceCode ruby"><code class="sourceCode ruby"><span id="cb41-1"><a href="#cb41-1" aria-hidden="true"></a><span class="co"># Class-based schema</span></span>
<span id="cb41-2"><a href="#cb41-2" aria-hidden="true"></a><span class="dt">YourSchema</span>.use(</span>
<span id="cb41-3"><a href="#cb41-3" aria-hidden="true"></a>    <span class="dt">GraphQL</span>::<span class="dt">Tracing</span>::<span class="dt">DataDogTracing</span>,</span>
<span id="cb41-4"><a href="#cb41-4" aria-hidden="true"></a>    <span class="st">service: 'graphql'</span></span>
<span id="cb41-5"><a href="#cb41-5" aria-hidden="true"></a>)</span></code></pre></div>
<div class="sourceCode" id="cb42"><pre class="sourceCode ruby"><code class="sourceCode ruby"><span id="cb42-1"><a href="#cb42-1" aria-hidden="true"></a><span class="co"># .define-style schema</span></span>
<span id="cb42-2"><a href="#cb42-2" aria-hidden="true"></a><span class="dt">YourSchema</span>.define <span class="kw">do</span></span>
<span id="cb42-3"><a href="#cb42-3" aria-hidden="true"></a>  use(</span>
<span id="cb42-4"><a href="#cb42-4" aria-hidden="true"></a>    <span class="dt">GraphQL</span>::<span class="dt">Tracing</span>::<span class="dt">DataDogTracing</span>,</span>
<span id="cb42-5"><a href="#cb42-5" aria-hidden="true"></a>    <span class="st">service: 'graphql'</span></span>
<span id="cb42-6"><a href="#cb42-6" aria-hidden="true"></a>  )</span>
<span id="cb42-7"><a href="#cb42-7" aria-hidden="true"></a><span class="kw">end</span></span></code></pre></div>
<p>Do <em>NOT</em> <code>instrument :graphql</code> in <code>Datadog.configure</code> if you choose to configure manually, as to avoid double tracing. These two means of configuring GraphQL tracing are considered mutually exclusive.</p>
<h3 id="grpc">gRPC</h3>
<p>The <code>grpc</code> integration adds both client and server interceptors, which run as middleware before executing the service’s remote procedure call. As gRPC applications are often distributed, the integration shares trace information between client and server.</p>
<p>To setup your integration, use the <code>Datadog.configure</code> method like so:</p>
<div class="sourceCode" id="cb43"><pre class="sourceCode ruby"><code class="sourceCode ruby"><span id="cb43-1"><a href="#cb43-1" aria-hidden="true"></a>require <span class="st">'grpc'</span></span>
<span id="cb43-2"><a href="#cb43-2" aria-hidden="true"></a>require <span class="st">'ddtrace'</span></span>
<span id="cb43-3"><a href="#cb43-3" aria-hidden="true"></a></span>
<span id="cb43-4"><a href="#cb43-4" aria-hidden="true"></a><span class="dt">Datadog</span>.configure <span class="kw">do</span> |c|</span>
<span id="cb43-5"><a href="#cb43-5" aria-hidden="true"></a>  c.tracing.instrument <span class="st">:grpc</span>, **options</span>
<span id="cb43-6"><a href="#cb43-6" aria-hidden="true"></a><span class="kw">end</span></span>
<span id="cb43-7"><a href="#cb43-7" aria-hidden="true"></a></span>
<span id="cb43-8"><a href="#cb43-8" aria-hidden="true"></a><span class="co"># Server side</span></span>
<span id="cb43-9"><a href="#cb43-9" aria-hidden="true"></a>server = <span class="dt">GRPC</span>::<span class="dt">RpcServer</span>.new</span>
<span id="cb43-10"><a href="#cb43-10" aria-hidden="true"></a>server.add_http2_port(<span class="st">'localhost:50051'</span>, <span class="st">:this_port_is_insecure</span>)</span>
<span id="cb43-11"><a href="#cb43-11" aria-hidden="true"></a>server.handle(<span class="dt">Demo</span>)</span>
<span id="cb43-12"><a href="#cb43-12" aria-hidden="true"></a>server.run_till_terminated</span>
<span id="cb43-13"><a href="#cb43-13" aria-hidden="true"></a></span>
<span id="cb43-14"><a href="#cb43-14" aria-hidden="true"></a><span class="co"># Client side</span></span>
<span id="cb43-15"><a href="#cb43-15" aria-hidden="true"></a>client = <span class="dt">Demo</span>.rpc_stub_class.new(<span class="st">'localhost:50051'</span>, <span class="st">:this_channel_is_insecure</span>)</span>
<span id="cb43-16"><a href="#cb43-16" aria-hidden="true"></a>client.my_endpoint(<span class="dt">DemoMessage</span>.new(<span class="st">contents: 'hello!'</span>))</span></code></pre></div>
<p><code>options</code> are the following keyword arguments:</p>
<table>
<colgroup>
<col style="width: 7%">
<col style="width: 9%">
<col style="width: 60%">
<col style="width: 22%">
</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_GRPC_SERVICE_NAME</code></td>
<td>Name of application running the <code>grpc</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>grpc</code></td>
</tr>
<tr class="even">
<td><code>peer_service</code></td>
<td><code>DD_TRACE_GRPC_PEER_SERVICE</code></td>
<td>Name of external service the application connects to</td>
<td><code>nil</code></td>
</tr>
<tr class="odd">
<td><code>distributed_tracing</code></td>
<td></td>
<td>Enables <a href="#distributed-tracing">distributed tracing</a>
</td>
<td><code>true</code></td>
</tr>
<tr class="even">
<td><code>server_error_handler</code></td>
<td></td>
<td>Custom error handler invoked when there is a server error. A <code>Proc</code> that accepts <code>span</code> and <code>error</code> parameters. 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="odd">
<td><code>client_error_handler</code></td>
<td></td>
<td>Custom error handler invoked when there is a client error. A <code>Proc</code> that accepts <code>span</code> and <code>error</code> parameters. Sets error on the span by default.</td>
<td><code>proc { \|span, error \| span.set_error(error) unless span.nil? }</code></td>
</tr>
</tbody>
</table>
<p>Deprecation notice: - <code>error_handler</code> will be removed. Use <code>server_error_handler</code> instead.</p>
<p><strong>Configuring clients to use different settings</strong></p>
<p>In situations where you have multiple clients calling multiple distinct services, you may pass the Datadog interceptor directly, like so</p>
<div class="sourceCode" id="cb44"><pre class="sourceCode ruby"><code class="sourceCode ruby"><span id="cb44-1"><a href="#cb44-1" aria-hidden="true"></a>configured_interceptor = <span class="dt">Datadog</span>::<span class="dt">Tracing</span>::<span class="dt">Contrib</span>::<span class="dt">GRPC</span>::<span class="dt">DatadogInterceptor</span>::<span class="dt">Client</span>.new <span class="kw">do</span> |c|</span>
<span id="cb44-2"><a href="#cb44-2" aria-hidden="true"></a>  c.service_name = <span class="st">"Alternate"</span></span>
<span id="cb44-3"><a href="#cb44-3" aria-hidden="true"></a><span class="kw">end</span></span>
<span id="cb44-4"><a href="#cb44-4" aria-hidden="true"></a></span>
<span id="cb44-5"><a href="#cb44-5" aria-hidden="true"></a>alternate_client = <span class="dt">Demo</span>::<span class="dt">Echo</span>::<span class="dt">Service</span>.rpc_stub_class.new(</span>
<span id="cb44-6"><a href="#cb44-6" aria-hidden="true"></a>  <span class="st">'localhost:50052'</span>,</span>
<span id="cb44-7"><a href="#cb44-7" aria-hidden="true"></a>  <span class="st">:this_channel_is_insecure</span>,</span>
<span id="cb44-8"><a href="#cb44-8" aria-hidden="true"></a>  <span class="st">:interceptors</span> =&gt; [configured_interceptor]</span>
<span id="cb44-9"><a href="#cb44-9" aria-hidden="true"></a>)</span></code></pre></div>
<p>The integration will ensure that the <code>configured_interceptor</code> establishes a unique tracing setup for that client instance.</p>
<h3 id="hanami">hanami</h3>
<p>The <code>hanami</code> integration will instrument routing, action and render for your hanami application. To enable the <code>hanami</code> instrumentation, it is recommended to auto instrument with</p>
<pre><code>gem 'ddtrace', require: 'ddtrace/auto_instrument'</code></pre>
<p>and create an initializer file in your <code>config/initializers</code> folder:</p>
<div class="sourceCode" id="cb46"><pre class="sourceCode ruby"><code class="sourceCode ruby"><span id="cb46-1"><a href="#cb46-1" aria-hidden="true"></a><span class="co"># config/initializers/datadog.rb</span></span>
<span id="cb46-2"><a href="#cb46-2" aria-hidden="true"></a><span class="dt">Datadog</span>.configure <span class="kw">do</span> |c|</span>
<span id="cb46-3"><a href="#cb46-3" aria-hidden="true"></a>  c.tracing.instrument <span class="st">:hanami</span>, **options</span>
<span id="cb46-4"><a href="#cb46-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>
<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>Service name for <code>hanami</code> instrumentation.</td>
<td><code>nil</code></td>
</tr>
</tbody>
</table>
<h3 id="http.rb">http.rb</h3>
<p>The http.rb integration will trace any HTTP call using the Http.rb gem.</p>
<div class="sourceCode" id="cb47"><pre class="sourceCode ruby"><code class="sourceCode ruby"><span id="cb47-1"><a href="#cb47-1" aria-hidden="true"></a>require <span class="st">'http'</span></span>
<span id="cb47-2"><a href="#cb47-2" aria-hidden="true"></a>require <span class="st">'ddtrace'</span></span>
<span id="cb47-3"><a href="#cb47-3" aria-hidden="true"></a><span class="dt">Datadog</span>.configure <span class="kw">do</span> |c|</span>
<span id="cb47-4"><a href="#cb47-4" aria-hidden="true"></a>  c.tracing.instrument <span class="st">:httprb</span>, **options</span>
<span id="cb47-5"><a href="#cb47-5" aria-hidden="true"></a>  <span class="co"># optionally, specify a different service name for hostnames matching a regex</span></span>
<span id="cb47-6"><a href="#cb47-6" aria-hidden="true"></a>  c.tracing.instrument <span class="st">:httprb</span>, <span class="st">describes: </span><span class="ot">/user-[^.]+\.example\.com/</span> <span class="kw">do</span> |httprb|</span>
<span id="cb47-7"><a href="#cb47-7" aria-hidden="true"></a>    httprb.service_name = <span class="st">'user.example.com'</span></span>
<span id="cb47-8"><a href="#cb47-8" aria-hidden="true"></a>    httprb.split_by_domain = <span class="dv">false</span> <span class="co"># Only necessary if split_by_domain is true by default</span></span>
<span id="cb47-9"><a href="#cb47-9" aria-hidden="true"></a>  <span class="kw">end</span></span>
<span id="cb47-10"><a href="#cb47-10" 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: 8%">
<col style="width: 15%">
<col style="width: 70%">
<col style="width: 4%">
</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_HTTPRB_SERVICE_NAME</code></td>
<td>Name of application running the <code>httprb</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>httprb</code></td>
</tr>
<tr class="even">
<td><code>peer_service</code></td>
<td><code>DD_TRACE_HTTPRB_PEER_SERVICE</code></td>
<td>Name of external service the application connects to</td>
<td><code>nil</code></td>
</tr>
<tr class="odd">
<td><code>distributed_tracing</code></td>
<td></td>
<td>Enables <a href="#distributed-tracing">distributed tracing</a>
</td>
<td><code>true</code></td>
</tr>
<tr class="even">
<td><code>split_by_domain</code></td>
<td></td>
<td>Uses the request domain as the service name when set to <code>true</code>.</td>
<td><code>false</code></td>
</tr>
<tr class="odd">
<td><code>error_status_codes</code></td>
<td><code>DD_TRACE_HTTPCLIENT_ERROR_STATUS_CODES</code></td>
<td>Range or Array of HTTP status codes that should be traced as errors.</td>
<td><code>400...600</code></td>
</tr>
</tbody>
</table>
<h3 id="httpclient">httpclient</h3>
<p>The httpclient integration will trace any HTTP call using the httpclient gem.</p>
<div class="sourceCode" id="cb48"><pre class="sourceCode ruby"><code class="sourceCode ruby"><span id="cb48-1"><a href="#cb48-1" aria-hidden="true"></a>require <span class="st">'httpclient'</span></span>
<span id="cb48-2"><a href="#cb48-2" aria-hidden="true"></a>require <span class="st">'ddtrace'</span></span>
<span id="cb48-3"><a href="#cb48-3" aria-hidden="true"></a><span class="dt">Datadog</span>.configure <span class="kw">do</span> |c|</span>
<span id="cb48-4"><a href="#cb48-4" aria-hidden="true"></a>  c.tracing.instrument <span class="st">:httpclient</span>, **options</span>
<span id="cb48-5"><a href="#cb48-5" aria-hidden="true"></a>  <span class="co"># optionally, specify a different service name for hostnames matching a regex</span></span>
<span id="cb48-6"><a href="#cb48-6" aria-hidden="true"></a>  c.tracing.instrument <span class="st">:httpclient</span>, <span class="st">describes: </span><span class="ot">/user-[^.]+\.example\.com/</span> <span class="kw">do</span> |httpclient|</span>
<span id="cb48-7"><a href="#cb48-7" aria-hidden="true"></a>    httpclient.service_name = <span class="st">'user.example.com'</span></span>
<span id="cb48-8"><a href="#cb48-8" aria-hidden="true"></a>    httpclient.split_by_domain = <span class="dv">false</span> <span class="co"># Only necessary if split_by_domain is true by default</span></span>
<span id="cb48-9"><a href="#cb48-9" aria-hidden="true"></a>  <span class="kw">end</span></span>
<span id="cb48-10"><a href="#cb48-10" 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: 8%">
<col style="width: 15%">
<col style="width: 70%">
<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>service_name</code></td>
<td><code>DD_TRACE_HTTPCLIENT_SERVICE_NAME</code></td>
<td>Name of application running the <code>httpclient</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>httpclient</code></td>
</tr>
<tr class="even">
<td><code>peer_service</code></td>
<td><code>DD_TRACE_HTTPCLIENT_PEER_SERVICE</code></td>
<td>Name of external service the application connects to</td>
<td><code>nil</code></td>
</tr>
<tr class="odd">
<td><code>distributed_tracing</code></td>
<td></td>
<td>Enables <a href="#distributed-tracing">distributed tracing</a>
</td>
<td><code>true</code></td>
</tr>
<tr class="even">
<td><code>split_by_domain</code></td>
<td></td>
<td>Uses the request domain as the service name when set to <code>true</code>.</td>
<td><code>false</code></td>
</tr>
<tr class="odd">
<td><code>error_status_codes</code></td>
<td><code>DD_TRACE_HTTPCLIENT_ERROR_STATUS_CODES</code></td>
<td>Range or Array of HTTP status codes that should be traced as errors.</td>
<td><code>400...600</code></td>
</tr>
</tbody>
</table>
<h3 id="httpx">httpx</h3>
<p><code>httpx</code> maintains its <a href="https://honeyryderchuck.gitlab.io/httpx/wiki/Datadog-Adapter">own integration with <code>ddtrace</code></a>:</p>
<div class="sourceCode" id="cb49"><pre class="sourceCode ruby"><code class="sourceCode ruby"><span id="cb49-1"><a href="#cb49-1" aria-hidden="true"></a>require <span class="st">"ddtrace"</span></span>
<span id="cb49-2"><a href="#cb49-2" aria-hidden="true"></a>require <span class="st">"httpx/adapters/datadog"</span></span>
<span id="cb49-3"><a href="#cb49-3" aria-hidden="true"></a></span>
<span id="cb49-4"><a href="#cb49-4" aria-hidden="true"></a><span class="dt">Datadog</span>.configure <span class="kw">do</span> |c|</span>
<span id="cb49-5"><a href="#cb49-5" aria-hidden="true"></a>  c.tracing.instrument <span class="st">:httpx</span></span>
<span id="cb49-6"><a href="#cb49-6" aria-hidden="true"></a></span>
<span id="cb49-7"><a href="#cb49-7" aria-hidden="true"></a>  <span class="co"># optionally, specify a different service name for hostnames matching a regex</span></span>
<span id="cb49-8"><a href="#cb49-8" aria-hidden="true"></a>  c.tracing.instrument <span class="st">:httpx</span>, <span class="st">describes: </span><span class="ot">/user-[^.]+\.example\.com/</span> <span class="kw">do</span> |http|</span>
<span id="cb49-9"><a href="#cb49-9" aria-hidden="true"></a>    http.service_name = <span class="st">'user.example.com'</span></span>
<span id="cb49-10"><a href="#cb49-10" aria-hidden="true"></a>    http.split_by_domain = <span class="dv">false</span> <span class="co"># Only necessary if split_by_domain is true by default</span></span>
<span id="cb49-11"><a href="#cb49-11" aria-hidden="true"></a>  <span class="kw">end</span></span>
<span id="cb49-12"><a href="#cb49-12" aria-hidden="true"></a><span class="kw">end</span></span></code></pre></div>
<h3 id="kafka">Kafka</h3>
<p>The Kafka integration provides tracing of the <code>ruby-kafka</code> gem:</p>
<p>You can enable it through <code>Datadog.configure</code>:</p>
<div class="sourceCode" id="cb50"><pre class="sourceCode ruby"><code class="sourceCode ruby"><span id="cb50-1"><a href="#cb50-1" aria-hidden="true"></a>require <span class="st">'active_support/notifications'</span> <span class="co"># required to enable 'ruby-kafka' instrumentation</span></span>
<span id="cb50-2"><a href="#cb50-2" aria-hidden="true"></a>require <span class="st">'kafka'</span></span>
<span id="cb50-3"><a href="#cb50-3" aria-hidden="true"></a>require <span class="st">'ddtrace'</span></span>
<span id="cb50-4"><a href="#cb50-4" aria-hidden="true"></a></span>
<span id="cb50-5"><a href="#cb50-5" aria-hidden="true"></a><span class="dt">Datadog</span>.configure <span class="kw">do</span> |c|</span>
<span id="cb50-6"><a href="#cb50-6" aria-hidden="true"></a>  c.tracing.instrument <span class="st">:kafka</span></span>
<span id="cb50-7"><a href="#cb50-7" aria-hidden="true"></a><span class="kw">end</span></span></code></pre></div>
<h3 id="minitest">Minitest</h3>
<p>The Minitest integration will trace all executions of tests when using <code>minitest</code> test framework.</p>
<p>To activate your integration, use the <code>Datadog.configure</code> method:</p>
<div class="sourceCode" id="cb51"><pre class="sourceCode ruby"><code class="sourceCode ruby"><span id="cb51-1"><a href="#cb51-1" aria-hidden="true"></a>require <span class="st">'minitest'</span></span>
<span id="cb51-2"><a href="#cb51-2" aria-hidden="true"></a>require <span class="st">'ddtrace'</span></span>
<span id="cb51-3"><a href="#cb51-3" aria-hidden="true"></a></span>
<span id="cb51-4"><a href="#cb51-4" aria-hidden="true"></a><span class="co"># Configure default Minitest integration</span></span>
<span id="cb51-5"><a href="#cb51-5" aria-hidden="true"></a><span class="dt">Datadog</span>.configure <span class="kw">do</span> |c|</span>
<span id="cb51-6"><a href="#cb51-6" aria-hidden="true"></a>  c.ci.instrument <span class="st">:minitest</span>, **options</span>
<span id="cb51-7"><a href="#cb51-7" 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 Minitest 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>minitest</code> instrumentation.</td>
<td><code>'minitest'</code></td>
</tr>
<tr class="odd">
<td><code>operation_name</code></td>
<td>Operation name used for <code>minitest</code> instrumentation. Useful if you want rename automatic trace metrics e.g. <code>trace.#{operation_name}.errors</code>.</td>
<td><code>'minitest.test'</code></td>
</tr>
</tbody>
</table>
<h3 id="mongodb">MongoDB</h3>
<p>The integration traces any <code>Command</code> that is sent from the <a href="https://github.com/mongodb/mongo-ruby-driver">MongoDB Ruby Driver</a> to a MongoDB cluster. By extension, Object Document Mappers (ODM) such as Mongoid are automatically instrumented if they use the official Ruby driver. To activate the integration, simply:</p>
<div class="sourceCode" id="cb52"><pre class="sourceCode ruby"><code class="sourceCode ruby"><span id="cb52-1"><a href="#cb52-1" aria-hidden="true"></a>require <span class="st">'mongo'</span></span>
<span id="cb52-2"><a href="#cb52-2" aria-hidden="true"></a>require <span class="st">'ddtrace'</span></span>
<span id="cb52-3"><a href="#cb52-3" aria-hidden="true"></a></span>
<span id="cb52-4"><a href="#cb52-4" aria-hidden="true"></a><span class="dt">Datadog</span>.configure <span class="kw">do</span> |c|</span>
<span id="cb52-5"><a href="#cb52-5" aria-hidden="true"></a>  c.tracing.instrument <span class="st">:mongo</span>, **options</span>
<span id="cb52-6"><a href="#cb52-6" aria-hidden="true"></a><span class="kw">end</span></span>
<span id="cb52-7"><a href="#cb52-7" aria-hidden="true"></a></span>
<span id="cb52-8"><a href="#cb52-8" aria-hidden="true"></a><span class="co"># Create a MongoDB client and use it as usual</span></span>
<span id="cb52-9"><a href="#cb52-9" aria-hidden="true"></a>client = <span class="dt">Mongo</span>::<span class="dt">Client</span>.new([ <span class="st">'127.0.0.1:27017'</span> ], <span class="st">:database</span> =&gt; <span class="st">'artists'</span>)</span>
<span id="cb52-10"><a href="#cb52-10" aria-hidden="true"></a>collection = client[<span class="st">:people</span>]</span>
<span id="cb52-11"><a href="#cb52-11" aria-hidden="true"></a>collection.insert_one({ <span class="st">name: 'Steve'</span> })</span>
<span id="cb52-12"><a href="#cb52-12" aria-hidden="true"></a></span>
<span id="cb52-13"><a href="#cb52-13" 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="cb52-14"><a href="#cb52-14" aria-hidden="true"></a><span class="dt">Datadog</span>.configure_onto(client, **options)</span></code></pre></div>
<p><code>options</code> are the following keyword arguments:</p>
<table>
<colgroup>
<col style="width: 5%">
<col style="width: 10%">
<col style="width: 66%">
<col style="width: 17%">
</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_MONGO_SERVICE_NAME</code></td>
<td>Name of application running the <code>mongo</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>mongodb</code></td>
</tr>
<tr class="even">
<td><code>peer_service</code></td>
<td><code>DD_TRACE_MONGO_PEER_SERVICE</code></td>
<td>Name of external service the application connects to</td>
<td><code>nil</code></td>
</tr>
<tr class="odd">
<td><code>quantize</code></td>
<td></td>
<td>Hash containing options for quantization. May include <code>:show</code> with an Array of keys to not quantize (or <code>:all</code> to skip quantization), or <code>:exclude</code> with Array of keys to exclude entirely.</td>
<td><code>{ show: [:collection, :database, :operation] }</code></td>
</tr>
</tbody>
</table>
<p><strong>Configuring trace settings per connection</strong></p>
<p>You can configure trace settings per connection by using the <code>describes</code> option:</p>
<div class="sourceCode" id="cb53"><pre class="sourceCode ruby"><code class="sourceCode ruby"><span id="cb53-1"><a href="#cb53-1" aria-hidden="true"></a><span class="co"># Provide a `:describes` option with a connection key.</span></span>
<span id="cb53-2"><a href="#cb53-2" aria-hidden="true"></a><span class="co"># Any of the following keys are acceptable and equivalent to one another.</span></span>
<span id="cb53-3"><a href="#cb53-3" aria-hidden="true"></a><span class="co"># If a block is provided, it yields a Settings object that</span></span>
<span id="cb53-4"><a href="#cb53-4" aria-hidden="true"></a><span class="co"># accepts any of the configuration options listed above.</span></span>
<span id="cb53-5"><a href="#cb53-5" aria-hidden="true"></a></span>
<span id="cb53-6"><a href="#cb53-6" aria-hidden="true"></a><span class="dt">Datadog</span>.configure <span class="kw">do</span> |c|</span>
<span id="cb53-7"><a href="#cb53-7" aria-hidden="true"></a>  <span class="co"># Network connection string</span></span>
<span id="cb53-8"><a href="#cb53-8" aria-hidden="true"></a>  c.tracing.instrument <span class="st">:mongo</span>, <span class="st">describes: '127.0.0.1:27017'</span>, <span class="st">service_name: 'mongo-primary'</span></span>
<span id="cb53-9"><a href="#cb53-9" aria-hidden="true"></a></span>
<span id="cb53-10"><a href="#cb53-10" aria-hidden="true"></a>  <span class="co"># Network connection regular expression</span></span>
<span id="cb53-11"><a href="#cb53-11" aria-hidden="true"></a>  c.tracing.instrument <span class="st">:mongo</span>, <span class="st">describes: </span><span class="ot">/localhost.*/</span>, <span class="st">service_name: 'mongo-secondary'</span></span>
<span id="cb53-12"><a href="#cb53-12" aria-hidden="true"></a><span class="kw">end</span></span>
<span id="cb53-13"><a href="#cb53-13" aria-hidden="true"></a></span>
<span id="cb53-14"><a href="#cb53-14" aria-hidden="true"></a>client = <span class="dt">Mongo</span>::<span class="dt">Client</span>.new([ <span class="st">'127.0.0.1:27017'</span> ], <span class="st">:database</span> =&gt; <span class="st">'artists'</span>)</span>
<span id="cb53-15"><a href="#cb53-15" aria-hidden="true"></a>collection = client[<span class="st">:people</span>]</span>
<span id="cb53-16"><a href="#cb53-16" aria-hidden="true"></a>collection.insert_one({ <span class="st">name: 'Steve'</span> })</span>
<span id="cb53-17"><a href="#cb53-17" aria-hidden="true"></a><span class="co"># Traced call will belong to `mongo-primary` service</span></span>
<span id="cb53-18"><a href="#cb53-18" aria-hidden="true"></a></span>
<span id="cb53-19"><a href="#cb53-19" aria-hidden="true"></a>client = <span class="dt">Mongo</span>::<span class="dt">Client</span>.new([ <span class="st">'localhost:27017'</span> ], <span class="st">:database</span> =&gt; <span class="st">'artists'</span>)</span>
<span id="cb53-20"><a href="#cb53-20" aria-hidden="true"></a>collection = client[<span class="st">:people</span>]</span>
<span id="cb53-21"><a href="#cb53-21" aria-hidden="true"></a>collection.insert_one({ <span class="st">name: 'Steve'</span> })</span>
<span id="cb53-22"><a href="#cb53-22" aria-hidden="true"></a><span class="co"># Traced call will belong to `mongo-secondary` service</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>
<h3 id="mysql2">MySQL2</h3>
<p>The MySQL2 integration traces any SQL command sent through <code>mysql2</code> gem.</p>
<div class="sourceCode" id="cb54"><pre class="sourceCode ruby"><code class="sourceCode ruby"><span id="cb54-1"><a href="#cb54-1" aria-hidden="true"></a>require <span class="st">'mysql2'</span></span>
<span id="cb54-2"><a href="#cb54-2" aria-hidden="true"></a>require <span class="st">'ddtrace'</span></span>
<span id="cb54-3"><a href="#cb54-3" aria-hidden="true"></a></span>
<span id="cb54-4"><a href="#cb54-4" aria-hidden="true"></a><span class="dt">Datadog</span>.configure <span class="kw">do</span> |c|</span>
<span id="cb54-5"><a href="#cb54-5" aria-hidden="true"></a>  c.tracing.instrument <span class="st">:mysql2</span>, **options</span>
<span id="cb54-6"><a href="#cb54-6" aria-hidden="true"></a><span class="kw">end</span></span>
<span id="cb54-7"><a href="#cb54-7" aria-hidden="true"></a></span>
<span id="cb54-8"><a href="#cb54-8" aria-hidden="true"></a>client = <span class="dt">Mysql2</span>::<span class="dt">Client</span>.new(<span class="st">:host</span> =&gt; <span class="st">"localhost"</span>, <span class="st">:username</span> =&gt; <span class="st">"root"</span>)</span>
<span id="cb54-9"><a href="#cb54-9" aria-hidden="true"></a>client.query(<span class="st">"SELECT * FROM users WHERE group='x'"</span>)</span></code></pre></div>
<p><code>options</code> are the following keyword arguments:</p>
<table>
<colgroup>
<col style="width: 5%">
<col style="width: 7%">
<col style="width: 83%">
<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_MYSQL2_SERVICE_NAME</code></td>
<td>Name of application running the <code>mysql2</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>mysql2</code></td>
</tr>
<tr class="even">
<td><code>peer_service</code></td>
<td><code>DD_TRACE_MYSQL2_PEER_SERVICE</code></td>
<td>Name of external service the application connects to</td>
<td><code>nil</code></td>
</tr>
<tr class="odd">
<td><code>comment_propagation</code></td>
<td><code>DD_DBM_PROPAGATION_MODE</code></td>
<td>SQL comment propagation mode for database monitoring. <br>(example: <code>disabled</code> | <code>service</code>| <code>full</code>). <br><br><strong>Important</strong>: <em>Note that enabling SQL comment propagation results in potentially confidential data (service names) being stored in the databases which can then be accessed by other third parties that have been granted access to the database.</em>
</td>
<td><code>'disabled'</code></td>
</tr>
<tr class="even">
<td><code>on_error</code></td>
<td></td>
<td>Custom error handler invoked when MySQL raises an error. Provided <code>span</code> and <code>error</code> as arguments. Sets error on the span by default. Useful for ignoring errors that are handled at the application level.</td>
<td><code>proc { \|span, error\| span.set_error(error) unless span.nil? }</code></td>
</tr>
</tbody>
</table>
<h3 id="nethttp">Net/HTTP</h3>
<p>The Net/HTTP integration will trace any HTTP call using the standard lib Net::HTTP module.</p>
<div class="sourceCode" id="cb55"><pre class="sourceCode ruby"><code class="sourceCode ruby"><span id="cb55-1"><a href="#cb55-1" aria-hidden="true"></a>require <span class="st">'net/http'</span></span>
<span id="cb55-2"><a href="#cb55-2" aria-hidden="true"></a>require <span class="st">'ddtrace'</span></span>
<span id="cb55-3"><a href="#cb55-3" aria-hidden="true"></a></span>
<span id="cb55-4"><a href="#cb55-4" aria-hidden="true"></a><span class="dt">Datadog</span>.configure <span class="kw">do</span> |c|</span>
<span id="cb55-5"><a href="#cb55-5" aria-hidden="true"></a>  c.tracing.instrument <span class="st">:http</span>, **options</span>
<span id="cb55-6"><a href="#cb55-6" aria-hidden="true"></a></span>
<span id="cb55-7"><a href="#cb55-7" aria-hidden="true"></a>  <span class="co"># optionally, specify a different service name for hostnames matching a regex</span></span>
<span id="cb55-8"><a href="#cb55-8" aria-hidden="true"></a>  c.tracing.instrument <span class="st">:http</span>, <span class="st">describes: </span><span class="ot">/user-[^.]+\.example\.com/</span> <span class="kw">do</span> |http|</span>
<span id="cb55-9"><a href="#cb55-9" aria-hidden="true"></a>    http.service_name = <span class="st">'user.example.com'</span></span>
<span id="cb55-10"><a href="#cb55-10" aria-hidden="true"></a>    http.split_by_domain = <span class="dv">false</span> <span class="co"># Only necessary if split_by_domain is true by default</span></span>
<span id="cb55-11"><a href="#cb55-11" aria-hidden="true"></a>  <span class="kw">end</span></span>
<span id="cb55-12"><a href="#cb55-12" aria-hidden="true"></a><span class="kw">end</span></span>
<span id="cb55-13"><a href="#cb55-13" aria-hidden="true"></a></span>
<span id="cb55-14"><a href="#cb55-14" aria-hidden="true"></a><span class="dt">Net</span>::<span class="dt">HTTP</span>.start(<span class="st">'127.0.0.1'</span>, <span class="dv">8080</span>) <span class="kw">do</span> |http|</span>
<span id="cb55-15"><a href="#cb55-15" aria-hidden="true"></a>  request = <span class="dt">Net</span>::<span class="dt">HTTP</span>::<span class="dt">Get</span>.new <span class="st">'/index'</span></span>
<span id="cb55-16"><a href="#cb55-16" aria-hidden="true"></a>  response = http.request(request)</span>
<span id="cb55-17"><a href="#cb55-17" aria-hidden="true"></a><span class="kw">end</span></span>
<span id="cb55-18"><a href="#cb55-18" aria-hidden="true"></a></span>
<span id="cb55-19"><a href="#cb55-19" aria-hidden="true"></a>content = <span class="dt">Net</span>::<span class="dt">HTTP</span>.get(<span class="dt">URI</span>(<span class="st">'http://127.0.0.1/index.html'</span>))</span></code></pre></div>
<p><code>options</code> are the following keyword arguments:</p>
<table>
<colgroup>
<col style="width: 8%">
<col style="width: 13%">
<col style="width: 72%">
<col style="width: 4%">
</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_NET_HTTP_SERVICE_NAME</code></td>
<td>Name of application running the <code>net/http</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>net/http</code></td>
</tr>
<tr class="even">
<td><code>peer_service</code></td>
<td><code>DD_TRACE_NET_HTTP_PEER_SERVICE</code></td>
<td>Name of external service the application connects to</td>
<td><code>nil</code></td>
</tr>
<tr class="odd">
<td><code>distributed_tracing</code></td>
<td></td>
<td>Enables <a href="#distributed-tracing">distributed tracing</a>
</td>
<td><code>true</code></td>
</tr>
<tr class="even">
<td><code>split_by_domain</code></td>
<td></td>
<td>Uses the request domain as the service name when set to <code>true</code>.</td>
<td><code>false</code></td>
</tr>
<tr class="odd">
<td><code>error_status_codes</code></td>
<td><code>DD_TRACE_HTTP_ERROR_STATUS_CODES</code></td>
<td>Range or Array of HTTP status codes that should be traced as errors.</td>
<td><code>400...600</code></td>
</tr>
</tbody>
</table>
<p>If you wish to configure each connection object individually, you may use the <code>Datadog.configure_onto</code> as it follows:</p>
<div class="sourceCode" id="cb56"><pre class="sourceCode ruby"><code class="sourceCode ruby"><span id="cb56-1"><a href="#cb56-1" aria-hidden="true"></a>client = <span class="dt">Net</span>::<span class="dt">HTTP</span>.new(host, port)</span>
<span id="cb56-2"><a href="#cb56-2" aria-hidden="true"></a><span class="dt">Datadog</span>.configure_onto(client, **options)</span></code></pre></div>
<h3 id="opensearch">OpenSearch</h3>
<p>The OpenSearch integration will trace any call to <code>perform_request</code> in the <code>Client</code> object:</p>
<div class="sourceCode" id="cb57"><pre class="sourceCode ruby"><code class="sourceCode ruby"><span id="cb57-1"><a href="#cb57-1" aria-hidden="true"></a>require <span class="st">'opensearch'</span></span>
<span id="cb57-2"><a href="#cb57-2" aria-hidden="true"></a>require <span class="st">'ddtrace'</span></span>
<span id="cb57-3"><a href="#cb57-3" aria-hidden="true"></a></span>
<span id="cb57-4"><a href="#cb57-4" aria-hidden="true"></a><span class="dt">Datadog</span>.configure <span class="kw">do</span> |c|</span>
<span id="cb57-5"><a href="#cb57-5" aria-hidden="true"></a>  c.tracing.instrument <span class="st">:opensearch</span>, **options</span>
<span id="cb57-6"><a href="#cb57-6" aria-hidden="true"></a><span class="kw">end</span></span>
<span id="cb57-7"><a href="#cb57-7" aria-hidden="true"></a></span>
<span id="cb57-8"><a href="#cb57-8" aria-hidden="true"></a><span class="co"># Perform a query to OpenSearch</span></span>
<span id="cb57-9"><a href="#cb57-9" aria-hidden="true"></a>client = <span class="dt">OpenSearch</span>::<span class="dt">Client</span>.new(</span>
<span id="cb57-10"><a href="#cb57-10" aria-hidden="true"></a>  <span class="st">host: 'https://localhost:9200'</span>,</span>
<span id="cb57-11"><a href="#cb57-11" aria-hidden="true"></a>  <span class="st">user: 'user'</span>,</span>
<span id="cb57-12"><a href="#cb57-12" aria-hidden="true"></a>  <span class="st">password: 'password'</span>,</span>
<span id="cb57-13"><a href="#cb57-13" aria-hidden="true"></a>)</span>
<span id="cb57-14"><a href="#cb57-14" aria-hidden="true"></a>client.cluster.health</span></code></pre></div>
<p><code>options</code> are the following keyword arguments:</p>
<table>
<colgroup>
<col style="width: 6%">
<col style="width: 13%">
<col style="width: 74%">
<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>service_name</code></td>
<td><code>DD_TRACE_OPENSEARCH_SERVICE_NAME</code></td>
<td>Name of application running the <code>opensearch</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>opensearch</code></td>
</tr>
<tr class="even">
<td><code>peer_service</code></td>
<td><code>DD_TRACE_OPENSEARCH_PEER_SERVICE</code></td>
<td>Name of external service the application connects to</td>
<td><code>nil</code></td>
</tr>
<tr class="odd">
<td><code>quantize</code></td>
<td></td>
<td>Hash containing options for quantization. May include <code>:show</code> with an Array of keys to not quantize (or <code>:all</code> to skip quantization), or <code>:exclude</code> with Array of keys to exclude entirely.</td>
<td><code>{}</code></td>
</tr>
</tbody>
</table>
<h3 id="postgres">Postgres</h3>
<p>The PG integration traces SQL commands sent through the <code>pg</code> gem via: * <code>exec</code>, <code>exec_params</code>, <code>exec_prepared</code>; * <code>async_exec</code>, <code>async_exec_params</code>, <code>async_exec_prepared</code>; or, * <code>sync_exec</code>, <code>sync_exec_params</code>, <code>sync_exec_prepared</code></p>
<div class="sourceCode" id="cb58"><pre class="sourceCode ruby"><code class="sourceCode ruby"><span id="cb58-1"><a href="#cb58-1" aria-hidden="true"></a>require <span class="st">'pg'</span></span>
<span id="cb58-2"><a href="#cb58-2" aria-hidden="true"></a>require <span class="st">'ddtrace'</span></span>
<span id="cb58-3"><a href="#cb58-3" aria-hidden="true"></a></span>
<span id="cb58-4"><a href="#cb58-4" aria-hidden="true"></a><span class="dt">Datadog</span>.configure <span class="kw">do</span> |c|</span>
<span id="cb58-5"><a href="#cb58-5" aria-hidden="true"></a>  c.tracing.instrument <span class="st">:pg</span>, **options</span>
<span id="cb58-6"><a href="#cb58-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: 5%">
<col style="width: 6%">
<col style="width: 84%">
<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_PG_SERVICE_NAME</code></td>
<td>Name of application running the <code>pg</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>pg</code></td>
</tr>
<tr class="even">
<td><code>peer_service</code></td>
<td><code>DD_TRACE_PG_PEER_SERVICE</code></td>
<td>Name of external service the application connects to</td>
<td><code>nil</code></td>
</tr>
<tr class="odd">
<td><code>comment_propagation</code></td>
<td><code>DD_DBM_PROPAGATION_MODE</code></td>
<td>SQL comment propagation mode for database monitoring. <br>(example: <code>disabled</code> | <code>service</code>| <code>full</code>). <br><br><strong>Important</strong>: <em>Note that enabling sql comment propagation results in potentially confidential data (service names) being stored in the databases which can then be accessed by other 3rd parties that have been granted access to the database.</em>
</td>
<td><code>'disabled'</code></td>
</tr>
<tr class="even">
<td><code>error_handler</code></td>
<td></td>
<td>Custom error handler invoked when raises an error. Provided <code>span</code> and <code>error</code> as arguments. Sets error on the span by default. Useful for ignoring errors that are handled at application level.</td>
<td><code>proc { \|span, error\| span.set_error(error) unless span.nil? }</code></td>
</tr>
</tbody>
</table>
<h3 id="presto">Presto</h3>
<p>The Presto integration traces any SQL command sent through <code>presto-client</code> gem.</p>
<div class="sourceCode" id="cb59"><pre class="sourceCode ruby"><code class="sourceCode ruby"><span id="cb59-1"><a href="#cb59-1" aria-hidden="true"></a>require <span class="st">'presto-client'</span></span>
<span id="cb59-2"><a href="#cb59-2" aria-hidden="true"></a>require <span class="st">'ddtrace'</span></span>
<span id="cb59-3"><a href="#cb59-3" aria-hidden="true"></a></span>
<span id="cb59-4"><a href="#cb59-4" aria-hidden="true"></a><span class="dt">Datadog</span>.configure <span class="kw">do</span> |c|</span>
<span id="cb59-5"><a href="#cb59-5" aria-hidden="true"></a>  c.tracing.instrument <span class="st">:presto</span>, **options</span>
<span id="cb59-6"><a href="#cb59-6" aria-hidden="true"></a><span class="kw">end</span></span>
<span id="cb59-7"><a href="#cb59-7" aria-hidden="true"></a></span>
<span id="cb59-8"><a href="#cb59-8" aria-hidden="true"></a>client = <span class="dt">Presto</span>::<span class="dt">Client</span>.new(</span>
<span id="cb59-9"><a href="#cb59-9" aria-hidden="true"></a>  <span class="st">server: "localhost:8880"</span>,</span>
<span id="cb59-10"><a href="#cb59-10" aria-hidden="true"></a>  <span class="st">ssl: </span>{<span class="st">verify: </span><span class="dv">false</span>},</span>
<span id="cb59-11"><a href="#cb59-11" aria-hidden="true"></a>  <span class="st">catalog: "native"</span>,</span>
<span id="cb59-12"><a href="#cb59-12" aria-hidden="true"></a>  <span class="st">schema: "default"</span>,</span>
<span id="cb59-13"><a href="#cb59-13" aria-hidden="true"></a>  <span class="st">time_zone: "US/Pacific"</span>,</span>
<span id="cb59-14"><a href="#cb59-14" aria-hidden="true"></a>  <span class="st">language: "English"</span>,</span>
<span id="cb59-15"><a href="#cb59-15" aria-hidden="true"></a>  <span class="st">http_debug: </span><span class="dv">true</span>,</span>
<span id="cb59-16"><a href="#cb59-16" aria-hidden="true"></a>)</span>
<span id="cb59-17"><a href="#cb59-17" aria-hidden="true"></a></span>
<span id="cb59-18"><a href="#cb59-18" aria-hidden="true"></a>client.run(<span class="st">"select * from system.nodes"</span>)</span></code></pre></div>
<p><code>options</code> are the following keyword arguments:</p>
<table>
<colgroup>
<col style="width: 9%">
<col style="width: 12%">
<col style="width: 74%">
<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_PRESTO_SERVICE_NAME</code></td>
<td>Name of application running the <code>presto</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>presto</code></td>
</tr>
<tr class="even">
<td><code>peer_service</code></td>
<td><code>DD_TRACE_PRESTO_PEER_SERVICE</code></td>
<td>Name of external service the application connects to</td>
<td><code>nil</code></td>
</tr>
</tbody>
</table>
<h3 id="qless">Qless</h3>
<p>The Qless integration uses lifecycle hooks to trace job executions.</p>
<p>To add tracing to a Qless job:</p>
<div class="sourceCode" id="cb60"><pre class="sourceCode ruby"><code class="sourceCode ruby"><span id="cb60-1"><a href="#cb60-1" aria-hidden="true"></a>require <span class="st">'ddtrace'</span></span>
<span id="cb60-2"><a href="#cb60-2" aria-hidden="true"></a></span>
<span id="cb60-3"><a href="#cb60-3" aria-hidden="true"></a><span class="dt">Datadog</span>.configure <span class="kw">do</span> |c|</span>
<span id="cb60-4"><a href="#cb60-4" aria-hidden="true"></a>  c.tracing.instrument <span class="st">:qless</span>, **options</span>
<span id="cb60-5"><a href="#cb60-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: 21%">
<col style="width: 56%">
<col style="width: 7%">
</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>tag_job_data</code></td>
<td><code>DD_QLESS_TAG_JOB_DATA</code></td>
<td>Enable tagging with job arguments. <code>true</code> for on, <code>false</code> for off.</td>
<td><code>false</code></td>
</tr>
<tr class="even">
<td><code>tag_job_tags</code></td>
<td><code>DD_QLESS_TAG_JOB_TAGS</code></td>
<td>Enable tagging with job tags. <code>true</code> for on, <code>false</code> for off.</td>
<td><code>false</code></td>
</tr>
</tbody>
</table>
<h3 id="que">Que</h3>
<p>The Que integration is a middleware which will trace job executions.</p>
<p>You can enable it through <code>Datadog.configure</code>:</p>
<div class="sourceCode" id="cb61"><pre class="sourceCode ruby"><code class="sourceCode ruby"><span id="cb61-1"><a href="#cb61-1" aria-hidden="true"></a>require <span class="st">'ddtrace'</span></span>
<span id="cb61-2"><a href="#cb61-2" aria-hidden="true"></a></span>
<span id="cb61-3"><a href="#cb61-3" aria-hidden="true"></a><span class="dt">Datadog</span>.configure <span class="kw">do</span> |c|</span>
<span id="cb61-4"><a href="#cb61-4" aria-hidden="true"></a>  c.tracing.instrument <span class="st">:que</span>, **options</span>
<span id="cb61-5"><a href="#cb61-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: 5%">
<col style="width: 11%">
<col style="width: 59%">
<col style="width: 23%">
</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>enabled</code></td>
<td><code>DD_TRACE_QUE_ENABLED</code></td>
<td>Defines whether Que 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>tag_args</code></td>
<td><code>DD_TRACE_QUE_TAG_ARGS_ENABLED</code></td>
<td>Enable tagging of a job’s args field. <code>true</code> for on, <code>false</code> for off.</td>
<td><code>false</code></td>
</tr>
<tr class="odd">
<td><code>tag_data</code></td>
<td><code>DD_TRACE_QUE_TAG_DATA_ENABLED</code></td>
<td>Enable tagging of a job’s data field. <code>true</code> for on, <code>false</code> for off.</td>
<td><code>false</code></td>
</tr>
<tr class="even">
<td><code>error_handler</code></td>
<td></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="racecar">Racecar</h3>
<p>The Racecar integration provides tracing for Racecar jobs.</p>
<p>You can enable it through <code>Datadog.configure</code>:</p>
<div class="sourceCode" id="cb62"><pre class="sourceCode ruby"><code class="sourceCode ruby"><span id="cb62-1"><a href="#cb62-1" aria-hidden="true"></a>require <span class="st">'ddtrace'</span></span>
<span id="cb62-2"><a href="#cb62-2" aria-hidden="true"></a></span>
<span id="cb62-3"><a href="#cb62-3" aria-hidden="true"></a><span class="dt">Datadog</span>.configure <span class="kw">do</span> |c|</span>
<span id="cb62-4"><a href="#cb62-4" aria-hidden="true"></a>  c.tracing.instrument <span class="st">:racecar</span>, **options</span>
<span id="cb62-5"><a href="#cb62-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: 8%">
<col style="width: 12%">
<col style="width: 73%">
<col style="width: 4%">
</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_RACECAR_SERVICE_NAME</code></td>
<td>Name of application running the <code>racecar</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>racecar</code></td>
</tr>
<tr class="even">
<td></td>
<td></td>
<td></td>
<td></td>
</tr>
</tbody>
</table>
<h3 id="rack">Rack</h3>
<p>The Rack integration provides a middleware that traces all requests before they reach the underlying framework or application. It responds to the Rack minimal interface, providing reasonable values that can be retrieved at the Rack level.</p>
<p>This integration is automatically activated with web frameworks like Rails. If you’re using a plain Rack application, enable the integration it to your <code>config.ru</code>:</p>
<div class="sourceCode" id="cb63"><pre class="sourceCode ruby"><code class="sourceCode ruby"><span id="cb63-1"><a href="#cb63-1" aria-hidden="true"></a><span class="co"># config.ru example</span></span>
<span id="cb63-2"><a href="#cb63-2" aria-hidden="true"></a>require <span class="st">'ddtrace'</span></span>
<span id="cb63-3"><a href="#cb63-3" aria-hidden="true"></a></span>
<span id="cb63-4"><a href="#cb63-4" aria-hidden="true"></a><span class="dt">Datadog</span>.configure <span class="kw">do</span> |c|</span>
<span id="cb63-5"><a href="#cb63-5" aria-hidden="true"></a>  c.tracing.instrument <span class="st">:rack</span>, **options</span>
<span id="cb63-6"><a href="#cb63-6" aria-hidden="true"></a><span class="kw">end</span></span>
<span id="cb63-7"><a href="#cb63-7" aria-hidden="true"></a></span>
<span id="cb63-8"><a href="#cb63-8" aria-hidden="true"></a>use <span class="dt">Datadog</span>::<span class="dt">Tracing</span>::<span class="dt">Contrib</span>::<span class="dt">Rack</span>::<span class="dt">TraceMiddleware</span></span>
<span id="cb63-9"><a href="#cb63-9" aria-hidden="true"></a></span>
<span id="cb63-10"><a href="#cb63-10" aria-hidden="true"></a>app = proc <span class="kw">do</span> |env|</span>
<span id="cb63-11"><a href="#cb63-11" aria-hidden="true"></a>  [ <span class="dv">200</span>, {<span class="st">'Content-Type'</span> =&gt; <span class="st">'text/plain'</span>}, [<span class="st">'OK'</span>] ]</span>
<span id="cb63-12"><a href="#cb63-12" aria-hidden="true"></a><span class="kw">end</span></span>
<span id="cb63-13"><a href="#cb63-13" aria-hidden="true"></a></span>
<span id="cb63-14"><a href="#cb63-14" aria-hidden="true"></a>run app</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>application</code></td>
<td>Your Rack application. Required for <code>middleware_names</code>.</td>
<td><code>nil</code></td>
</tr>
<tr class="even">
<td><code>distributed_tracing</code></td>
<td>Enables <a href="#distributed-tracing">distributed tracing</a> so that this service trace is connected with a trace of another service if tracing headers are received</td>
<td><code>true</code></td>
</tr>
<tr class="odd">
<td><code>headers</code></td>
<td>Hash of HTTP request or response headers to add as tags to the <code>rack.request</code>. Accepts <code>request</code> and <code>response</code> keys with Array values e.g. <code>['Last-Modified']</code>. Adds <code>http.request.headers.*</code> and <code>http.response.headers.*</code> tags respectively. This option overrides the global <code>DD_TRACE_HEADER_TAGS</code>, see <a href="https://docs.datadoghq.com/tracing/configure_data_security/#applying-header-tags-to-root-spans">Applying header tags to root spans</a> for more information.</td>
<td><code>{ response: ['Content-Type', 'X-Request-ID'] }</code></td>
</tr>
<tr class="even">
<td><code>middleware_names</code></td>
<td>Enable this if you want to use the last executed middleware class as the resource name for the <code>rack</code> span. If enabled alongside the <code>rails</code> instrumention, <code>rails</code> takes precedence by setting the <code>rack</code> resource name to the active <code>rails</code> controller when applicable. Requires <code>application</code> option to use.</td>
<td><code>false</code></td>
</tr>
<tr class="odd">
<td><code>quantize</code></td>
<td>Hash containing options for quantization. May include <code>:query</code> or <code>:fragment</code>.</td>
<td><code>{}</code></td>
</tr>
<tr class="even">
<td><code>quantize.base</code></td>
<td>Defines behavior for URL base (scheme, host, port). May be <code>:show</code> to keep URL base in <code>http.url</code> tag and not set <code>http.base_url</code> tag, or <code>nil</code> to remove URL base from <code>http.url</code> tag by default, leaving a path and setting <code>http.base_url</code>. Option must be nested inside the <code>quantize</code> option.</td>
<td><code>nil</code></td>
</tr>
<tr class="odd">
<td><code>quantize.query</code></td>
<td>Hash containing options for query portion of URL quantization. May include <code>:show</code> or <code>:exclude</code>. See options below. Option must be nested inside the <code>quantize</code> option.</td>
<td><code>{}</code></td>
</tr>
<tr class="even">
<td><code>quantize.query.show</code></td>
<td>Defines which values should always be shown. May be an Array of strings, <code>:all</code> to show all values, or <code>nil</code> to show no values. Option must be nested inside the <code>query</code> option.</td>
<td><code>nil</code></td>
</tr>
<tr class="odd">
<td><code>quantize.query.exclude</code></td>
<td>Defines which values should be removed entirely. May be an Array of strings, <code>:all</code> to remove the query string entirely, or <code>nil</code> to exclude nothing. Option must be nested inside the <code>query</code> option.</td>
<td><code>nil</code></td>
</tr>
<tr class="even">
<td><code>quantize.query.obfuscate</code></td>
<td>Defines query string redaction behaviour. May be a hash of options, <code>:internal</code> to use the default internal obfuscation settings, or <code>nil</code> to disable obfuscation. Note that obfuscation is a string-wise operation, not a key-value operation. When enabled, <code>query.show</code> defaults to <code>:all</code> if otherwise unset. Option must be nested inside the <code>query</code> option.</td>
<td><code>nil</code></td>
</tr>
<tr class="odd">
<td><code>quantize.query.obfuscate.with</code></td>
<td>Defines the string to replace obfuscated matches with. May be a String. Option must be nested inside the <code>query.obfuscate</code> option.</td>
<td><code>'&lt;redacted&gt;'</code></td>
</tr>
<tr class="even">
<td><code>quantize.query.obfuscate.regex</code></td>
<td>Defines the regex with which the query string will be redacted. May be a Regexp, or <code>:internal</code> to use the default internal Regexp, which redacts well-known sensitive data. Each match is redacted entirely by replacing it with <code>query.obfuscate.with</code>. Option must be nested inside the <code>query.obfuscate</code> option.</td>
<td><code>:internal</code></td>
</tr>
<tr class="odd">
<td><code>quantize.fragment</code></td>
<td>Defines behavior for URL fragments. May be <code>:show</code> to show URL fragments, or <code>nil</code> to remove fragments. Option must be nested inside the <code>quantize</code> option.</td>
<td><code>nil</code></td>
</tr>
<tr class="even">
<td><code>request_queuing</code></td>
<td>Track HTTP request time spent in the queue of the frontend server. See <a href="#http-request-queuing">HTTP request queuing</a> for setup details.</td>
<td><code>false</code></td>
</tr>
<tr class="odd">
<td><code>web_service_name</code></td>
<td>Service name for frontend server request queuing spans. (e.g. <code>'nginx'</code>)</td>
<td><code>'web-server'</code></td>
</tr>
</tbody>
</table>
<p>Deprecation notice: - <code>quantize.base</code> will change its default from <code>:exclude</code> to <code>:show</code> in a future version. Voluntarily moving to <code>:show</code> is recommended. - <code>quantize.query.show</code> will change its default to <code>:all</code> in a future version, together with <code>quantize.query.obfuscate</code> changing to <code>:internal</code>. Voluntarily moving to these future values is recommended.</p>
<p><strong>Configuring URL quantization behavior</strong></p>
<div class="sourceCode" id="cb64"><pre class="sourceCode ruby"><code class="sourceCode ruby"><span id="cb64-1"><a href="#cb64-1" aria-hidden="true"></a><span class="dt">Datadog</span>.configure <span class="kw">do</span> |c|</span>
<span id="cb64-2"><a href="#cb64-2" aria-hidden="true"></a>  <span class="co"># Default behavior: all values are quantized, base is removed, fragment is removed.</span></span>
<span id="cb64-3"><a href="#cb64-3" aria-hidden="true"></a>  <span class="co"># http://example.com/path?category_id=1&amp;sort_by=asc#featured --&gt; /path?category_id&amp;sort_by</span></span>
<span id="cb64-4"><a href="#cb64-4" aria-hidden="true"></a>  <span class="co"># http://example.com:8080/path?categories[]=1&amp;categories[]=2 --&gt; /path?categories[]</span></span>
<span id="cb64-5"><a href="#cb64-5" aria-hidden="true"></a></span>
<span id="cb64-6"><a href="#cb64-6" aria-hidden="true"></a>  <span class="co"># Remove URL base (scheme, host, port)</span></span>
<span id="cb64-7"><a href="#cb64-7" aria-hidden="true"></a>  <span class="co"># http://example.com/path?category_id=1&amp;sort_by=asc#featured --&gt; /path?category_id&amp;sort_by#featured</span></span>
<span id="cb64-8"><a href="#cb64-8" aria-hidden="true"></a>  c.tracing.instrument <span class="st">:rack</span>, <span class="st">quantize: </span>{ <span class="st">base: :exclude</span> }</span>
<span id="cb64-9"><a href="#cb64-9" aria-hidden="true"></a></span>
<span id="cb64-10"><a href="#cb64-10" aria-hidden="true"></a>  <span class="co"># Show URL base</span></span>
<span id="cb64-11"><a href="#cb64-11" aria-hidden="true"></a>  <span class="co"># http://example.com/path?category_id=1&amp;sort_by=asc#featured --&gt; http://example.com/path?category_id&amp;sort_by#featured</span></span>
<span id="cb64-12"><a href="#cb64-12" aria-hidden="true"></a>  c.tracing.instrument <span class="st">:rack</span>, <span class="st">quantize: </span>{ <span class="st">base: :show</span> }</span>
<span id="cb64-13"><a href="#cb64-13" aria-hidden="true"></a></span>
<span id="cb64-14"><a href="#cb64-14" aria-hidden="true"></a>  <span class="co"># Show values for any query string parameter matching 'category_id' exactly</span></span>
<span id="cb64-15"><a href="#cb64-15" aria-hidden="true"></a>  <span class="co"># http://example.com/path?category_id=1&amp;sort_by=asc#featured --&gt; /path?category_id=1&amp;sort_by</span></span>
<span id="cb64-16"><a href="#cb64-16" aria-hidden="true"></a>  c.tracing.instrument <span class="st">:rack</span>, <span class="st">quantize: </span>{ <span class="st">query: </span>{ <span class="st">show: </span>[<span class="st">'category_id'</span>] } }</span>
<span id="cb64-17"><a href="#cb64-17" aria-hidden="true"></a></span>
<span id="cb64-18"><a href="#cb64-18" aria-hidden="true"></a>  <span class="co"># Show all values for all query string parameters</span></span>
<span id="cb64-19"><a href="#cb64-19" aria-hidden="true"></a>  <span class="co"># http://example.com/path?category_id=1&amp;sort_by=asc#featured --&gt; /path?category_id=1&amp;sort_by=asc</span></span>
<span id="cb64-20"><a href="#cb64-20" aria-hidden="true"></a>  c.tracing.instrument <span class="st">:rack</span>, <span class="st">quantize: </span>{ <span class="st">query: </span>{ <span class="st">show: :all</span> } }</span>
<span id="cb64-21"><a href="#cb64-21" aria-hidden="true"></a></span>
<span id="cb64-22"><a href="#cb64-22" aria-hidden="true"></a>  <span class="co"># Totally exclude any query string parameter matching 'sort_by' exactly</span></span>
<span id="cb64-23"><a href="#cb64-23" aria-hidden="true"></a>  <span class="co"># http://example.com/path?category_id=1&amp;sort_by=asc#featured --&gt; /path?category_id</span></span>
<span id="cb64-24"><a href="#cb64-24" aria-hidden="true"></a>  c.tracing.instrument <span class="st">:rack</span>, <span class="st">quantize: </span>{ <span class="st">query: </span>{ <span class="st">exclude: </span>[<span class="st">'sort_by'</span>] } }</span>
<span id="cb64-25"><a href="#cb64-25" aria-hidden="true"></a></span>
<span id="cb64-26"><a href="#cb64-26" aria-hidden="true"></a>  <span class="co"># Remove the query string entirely</span></span>
<span id="cb64-27"><a href="#cb64-27" aria-hidden="true"></a>  <span class="co"># http://example.com/path?category_id=1&amp;sort_by=asc#featured --&gt; /path</span></span>
<span id="cb64-28"><a href="#cb64-28" aria-hidden="true"></a>  c.tracing.instrument <span class="st">:rack</span>, <span class="st">quantize: </span>{ <span class="st">query: </span>{ <span class="st">exclude: :all</span> } }</span>
<span id="cb64-29"><a href="#cb64-29" aria-hidden="true"></a></span>
<span id="cb64-30"><a href="#cb64-30" aria-hidden="true"></a>  <span class="co"># Show URL fragments</span></span>
<span id="cb64-31"><a href="#cb64-31" aria-hidden="true"></a>  <span class="co"># http://example.com/path?category_id=1&amp;sort_by=asc#featured --&gt; /path?category_id&amp;sort_by#featured</span></span>
<span id="cb64-32"><a href="#cb64-32" aria-hidden="true"></a>  c.tracing.instrument <span class="st">:rack</span>, <span class="st">quantize: </span>{ <span class="st">fragment: :show</span> }</span>
<span id="cb64-33"><a href="#cb64-33" aria-hidden="true"></a></span>
<span id="cb64-34"><a href="#cb64-34" aria-hidden="true"></a>  <span class="co"># Obfuscate query string, defaulting to showing all values</span></span>
<span id="cb64-35"><a href="#cb64-35" aria-hidden="true"></a>  <span class="co"># http://example.com/path?password=qwerty&amp;sort_by=asc#featured --&gt; /path?&lt;redacted&gt;&amp;sort_by=asc</span></span>
<span id="cb64-36"><a href="#cb64-36" aria-hidden="true"></a>  c.tracing.instrument <span class="st">:rack</span>, <span class="st">quantize: </span>{ <span class="st">query: </span>{ <span class="st">obfuscate: </span>{} } }</span>
<span id="cb64-37"><a href="#cb64-37" aria-hidden="true"></a></span>
<span id="cb64-38"><a href="#cb64-38" aria-hidden="true"></a>  <span class="co"># Obfuscate query string using the provided regex, defaulting to showing all values</span></span>
<span id="cb64-39"><a href="#cb64-39" aria-hidden="true"></a>  <span class="co"># http://example.com/path?category_id=1&amp;sort_by=asc#featured --&gt; /path?&lt;redacted&gt;&amp;sort_by=asc</span></span>
<span id="cb64-40"><a href="#cb64-40" aria-hidden="true"></a>  c.tracing.instrument <span class="st">:rack</span>, <span class="st">quantize: </span>{ <span class="st">query: </span>{ <span class="st">obfuscate: </span>{ <span class="st">regex: </span><span class="ot">/category_id=\d+/</span> } } }</span>
<span id="cb64-41"><a href="#cb64-41" aria-hidden="true"></a></span>
<span id="cb64-42"><a href="#cb64-42" aria-hidden="true"></a>  <span class="co"># Obfuscate query string using a custom redaction string</span></span>
<span id="cb64-43"><a href="#cb64-43" aria-hidden="true"></a>  <span class="co"># http://example.com/path?password=qwerty&amp;sort_by=asc#featured --&gt; /path?REMOVED&amp;sort_by=asc</span></span>
<span id="cb64-44"><a href="#cb64-44" aria-hidden="true"></a>  c.tracing.instrument <span class="st">:rack</span>, <span class="st">quantize: </span>{ <span class="st">query: </span>{ <span class="st">obfuscate: </span>{ <span class="st">with: 'REMOVED'</span> } } }</span>
<span id="cb64-45"><a href="#cb64-45" aria-hidden="true"></a><span class="kw">end</span></span></code></pre></div>
<h3 id="rails">Rails</h3>
<p>The Rails integration will trace requests, database calls, templates rendering, and cache read/write/delete operations. The integration makes use of the Active Support Instrumentation, listening to the Notification API so that any operation instrumented by the API is traced.</p>
<p>To enable the Rails instrumentation, create an initializer file in your <code>config/initializers</code> folder:</p>
<div class="sourceCode" id="cb65"><pre class="sourceCode ruby"><code class="sourceCode ruby"><span id="cb65-1"><a href="#cb65-1" aria-hidden="true"></a><span class="co"># config/initializers/datadog.rb</span></span>
<span id="cb65-2"><a href="#cb65-2" aria-hidden="true"></a>require <span class="st">'ddtrace'</span></span>
<span id="cb65-3"><a href="#cb65-3" aria-hidden="true"></a></span>
<span id="cb65-4"><a href="#cb65-4" aria-hidden="true"></a><span class="dt">Datadog</span>.configure <span class="kw">do</span> |c|</span>
<span id="cb65-5"><a href="#cb65-5" aria-hidden="true"></a>  c.tracing.instrument <span class="st">:rails</span>, **options</span>
<span id="cb65-6"><a href="#cb65-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: 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>distributed_tracing</code></td>
<td>Enables <a href="#distributed-tracing">distributed tracing</a> so that this service trace is connected with a trace of another service if tracing headers are received</td>
<td><code>true</code></td>
</tr>
<tr class="even">
<td><code>request_queuing</code></td>
<td>Track HTTP request time spent in the queue of the frontend server. See <a href="#http-request-queuing">HTTP request queuing</a> for setup details.</td>
<td><code>false</code></td>
</tr>
<tr class="odd">
<td><code>middleware</code></td>
<td>Add the trace middleware to the Rails application. Set to <code>false</code> if you don’t want the middleware to load.</td>
<td><code>true</code></td>
</tr>
<tr class="even">
<td><code>middleware_names</code></td>
<td>Enables any short-circuited middleware requests to display the middleware name as a resource for the trace.</td>
<td><code>false</code></td>
</tr>
<tr class="odd">
<td><code>service_name</code></td>
<td>Service name used when tracing application requests (on the <code>rack</code> level)</td>
<td>
<code>'&lt;app_name&gt;'</code> (inferred from your Rails application namespace)</td>
</tr>
<tr class="even">
<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>
<p><strong>Supported versions</strong></p>
<table>
<thead>
<tr class="header">
<th>MRI Versions</th>
<th>JRuby Versions</th>
<th>Rails Versions</th>
</tr>
</thead>
<tbody>
<tr class="odd">
<td>2.1</td>
<td></td>
<td>3.2 - 4.2</td>
</tr>
<tr class="even">
<td>2.2 - 2.3</td>
<td></td>
<td>3.2 - 5.2</td>
</tr>
<tr class="odd">
<td>2.4</td>
<td></td>
<td>4.2.8 - 5.2</td>
</tr>
<tr class="even">
<td>2.5</td>
<td></td>
<td>4.2.8 - 6.1</td>
</tr>
<tr class="odd">
<td>2.6 - 2.7</td>
<td>9.2</td>
<td>5.0 - 6.1</td>
</tr>
<tr class="even">
<td>3.0 - 3.2</td>
<td></td>
<td>6.1</td>
</tr>
</tbody>
</table>
<h3 id="rake">Rake</h3>
<p>You can add instrumentation around your Rake tasks by activating the <code>rake</code> integration and providing a list of what Rake tasks need to be instrumented.</p>
<p><strong>Avoid instrumenting long-running Rake tasks, as such tasks can aggregate large traces in memory that are never flushed until the task finishes.</strong></p>
<p>For long-running tasks, use <a href="#manual-instrumentation">Manual instrumentation</a> around recurring code paths.</p>
<p>To activate Rake task tracing, add the following to your <code>Rakefile</code>:</p>
<div class="sourceCode" id="cb66"><pre class="sourceCode ruby"><code class="sourceCode ruby"><span id="cb66-1"><a href="#cb66-1" aria-hidden="true"></a><span class="co"># At the top of your Rakefile:</span></span>
<span id="cb66-2"><a href="#cb66-2" aria-hidden="true"></a>require <span class="st">'rake'</span></span>
<span id="cb66-3"><a href="#cb66-3" aria-hidden="true"></a>require <span class="st">'ddtrace'</span></span>
<span id="cb66-4"><a href="#cb66-4" aria-hidden="true"></a></span>
<span id="cb66-5"><a href="#cb66-5" aria-hidden="true"></a><span class="dt">Datadog</span>.configure <span class="kw">do</span> |c|</span>
<span id="cb66-6"><a href="#cb66-6" aria-hidden="true"></a>  c.tracing.instrument <span class="st">:rake</span>, <span class="st">tasks: </span>[<span class="st">'my_task'</span>], **options</span>
<span id="cb66-7"><a href="#cb66-7" aria-hidden="true"></a><span class="kw">end</span></span>
<span id="cb66-8"><a href="#cb66-8" aria-hidden="true"></a></span>
<span id="cb66-9"><a href="#cb66-9" aria-hidden="true"></a>task <span class="st">:my_task</span> <span class="kw">do</span></span>
<span id="cb66-10"><a href="#cb66-10" aria-hidden="true"></a>  <span class="co"># Do something task work here...</span></span>
<span id="cb66-11"><a href="#cb66-11" aria-hidden="true"></a><span class="kw">end</span></span>
<span id="cb66-12"><a href="#cb66-12" aria-hidden="true"></a></span>
<span id="cb66-13"><a href="#cb66-13" aria-hidden="true"></a><span class="dt">Rake</span>::<span class="dt">Task</span>[<span class="st">'my_task'</span>].invoke</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 Rake tasks 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>quantize</code></td>
<td>Hash containing options for quantization of task arguments. See below for more details and examples.</td>
<td><code>{}</code></td>
</tr>
<tr class="odd">
<td><code>service_name</code></td>
<td>Service name used for <code>rake</code> instrumentation</td>
<td><code>'rake'</code></td>
</tr>
<tr class="even">
<td><code>tasks</code></td>
<td>Names of the Rake tasks to instrument</td>
<td><code>[]</code></td>
</tr>
</tbody>
</table>
<p><strong>Configuring task quantization behavior</strong></p>
<div class="sourceCode" id="cb67"><pre class="sourceCode ruby"><code class="sourceCode ruby"><span id="cb67-1"><a href="#cb67-1" aria-hidden="true"></a><span class="dt">Datadog</span>.configure <span class="kw">do</span> |c|</span>
<span id="cb67-2"><a href="#cb67-2" aria-hidden="true"></a>  <span class="co"># Given a task that accepts :one, :two, :three...</span></span>
<span id="cb67-3"><a href="#cb67-3" aria-hidden="true"></a>  <span class="co"># Invoked with 'foo', 'bar', 'baz'.</span></span>
<span id="cb67-4"><a href="#cb67-4" aria-hidden="true"></a></span>
<span id="cb67-5"><a href="#cb67-5" aria-hidden="true"></a>  <span class="co"># Default behavior: all arguments are quantized.</span></span>
<span id="cb67-6"><a href="#cb67-6" aria-hidden="true"></a>  <span class="co"># `rake.invoke.args` tag  --&gt; ['?']</span></span>
<span id="cb67-7"><a href="#cb67-7" aria-hidden="true"></a>  <span class="co"># `rake.execute.args` tag --&gt; { one: '?', two: '?', three: '?' }</span></span>
<span id="cb67-8"><a href="#cb67-8" aria-hidden="true"></a>  c.tracing.instrument <span class="st">:rake</span></span>
<span id="cb67-9"><a href="#cb67-9" aria-hidden="true"></a></span>
<span id="cb67-10"><a href="#cb67-10" aria-hidden="true"></a>  <span class="co"># Show values for any argument matching :two exactly</span></span>
<span id="cb67-11"><a href="#cb67-11" aria-hidden="true"></a>  <span class="co"># `rake.invoke.args` tag  --&gt; ['?']</span></span>
<span id="cb67-12"><a href="#cb67-12" aria-hidden="true"></a>  <span class="co"># `rake.execute.args` tag --&gt; { one: '?', two: 'bar', three: '?' }</span></span>
<span id="cb67-13"><a href="#cb67-13" aria-hidden="true"></a>  c.tracing.instrument <span class="st">:rake</span>, <span class="st">quantize: </span>{ <span class="st">args: </span>{ <span class="st">show: </span>[<span class="st">:two</span>] } }</span>
<span id="cb67-14"><a href="#cb67-14" aria-hidden="true"></a></span>
<span id="cb67-15"><a href="#cb67-15" aria-hidden="true"></a>  <span class="co"># Show all values for all arguments.</span></span>
<span id="cb67-16"><a href="#cb67-16" aria-hidden="true"></a>  <span class="co"># `rake.invoke.args` tag  --&gt; ['foo', 'bar', 'baz']</span></span>
<span id="cb67-17"><a href="#cb67-17" aria-hidden="true"></a>  <span class="co"># `rake.execute.args` tag --&gt; { one: 'foo', two: 'bar', three: 'baz' }</span></span>
<span id="cb67-18"><a href="#cb67-18" aria-hidden="true"></a>  c.tracing.instrument <span class="st">:rake</span>, <span class="st">quantize: </span>{ <span class="st">args: </span>{ <span class="st">show: :all</span> } }</span>
<span id="cb67-19"><a href="#cb67-19" aria-hidden="true"></a></span>
<span id="cb67-20"><a href="#cb67-20" aria-hidden="true"></a>  <span class="co"># Totally exclude any argument matching :three exactly</span></span>
<span id="cb67-21"><a href="#cb67-21" aria-hidden="true"></a>  <span class="co"># `rake.invoke.args` tag  --&gt; ['?']</span></span>
<span id="cb67-22"><a href="#cb67-22" aria-hidden="true"></a>  <span class="co"># `rake.execute.args` tag --&gt; { one: '?', two: '?' }</span></span>
<span id="cb67-23"><a href="#cb67-23" aria-hidden="true"></a>  c.tracing.instrument <span class="st">:rake</span>, <span class="st">quantize: </span>{ <span class="st">args: </span>{ <span class="st">exclude: </span>[<span class="st">:three</span>] } }</span>
<span id="cb67-24"><a href="#cb67-24" aria-hidden="true"></a></span>
<span id="cb67-25"><a href="#cb67-25" aria-hidden="true"></a>  <span class="co"># Remove the arguments entirely</span></span>
<span id="cb67-26"><a href="#cb67-26" aria-hidden="true"></a>  <span class="co"># `rake.invoke.args` tag  --&gt; ['?']</span></span>
<span id="cb67-27"><a href="#cb67-27" aria-hidden="true"></a>  <span class="co"># `rake.execute.args` tag --&gt; {}</span></span>
<span id="cb67-28"><a href="#cb67-28" aria-hidden="true"></a>  c.tracing.instrument <span class="st">:rake</span>, <span class="st">quantize: </span>{ <span class="st">args: </span>{ <span class="st">exclude: :all</span> } }</span>
<span id="cb67-29"><a href="#cb67-29" aria-hidden="true"></a><span class="kw">end</span></span></code></pre></div>
<h3 id="redis">Redis</h3>
<p>The Redis integration will trace simple calls as well as pipelines.</p>
<div class="sourceCode" id="cb68"><pre class="sourceCode ruby"><code class="sourceCode ruby"><span id="cb68-1"><a href="#cb68-1" aria-hidden="true"></a>require <span class="st">'redis'</span></span>
<span id="cb68-2"><a href="#cb68-2" aria-hidden="true"></a>require <span class="st">'ddtrace'</span></span>
<span id="cb68-3"><a href="#cb68-3" aria-hidden="true"></a></span>
<span id="cb68-4"><a href="#cb68-4" aria-hidden="true"></a><span class="dt">Datadog</span>.configure <span class="kw">do</span> |c|</span>
<span id="cb68-5"><a href="#cb68-5" aria-hidden="true"></a>  c.tracing.instrument <span class="st">:redis</span>, **options</span>
<span id="cb68-6"><a href="#cb68-6" aria-hidden="true"></a><span class="kw">end</span></span>
<span id="cb68-7"><a href="#cb68-7" aria-hidden="true"></a></span>
<span id="cb68-8"><a href="#cb68-8" aria-hidden="true"></a><span class="co"># Perform Redis commands</span></span>
<span id="cb68-9"><a href="#cb68-9" aria-hidden="true"></a>redis = <span class="dt">Redis</span>.new</span>
<span id="cb68-10"><a href="#cb68-10" aria-hidden="true"></a>redis.set <span class="st">'foo'</span>, <span class="st">'bar'</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: 76%">
<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_REDIS_SERVICE_NAME</code></td>
<td>Name of application running the <code>redis</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>redis</code></td>
</tr>
<tr class="even">
<td><code>peer_service</code></td>
<td><code>DD_TRACE_REDIS_PEER_SERVICE</code></td>
<td>Name of external service the application connects to</td>
<td><code>nil</code></td>
</tr>
<tr class="odd">
<td><code>command_args</code></td>
<td><code>DD_REDIS_COMMAND_ARGS</code></td>
<td>Show the command arguments (for example, <code>key</code> in <code>GET key</code>) as resource name and tag. If <code>false</code>, only the command name is shown (for example, <code>GET</code>).</td>
<td>false</td>
</tr>
</tbody>
</table>
<p><strong>Configuring trace settings per instance</strong></p>
<p>With Redis version &gt;= 5:</p>
<div class="sourceCode" id="cb69"><pre class="sourceCode ruby"><code class="sourceCode ruby"><span id="cb69-1"><a href="#cb69-1" aria-hidden="true"></a>require <span class="st">'redis'</span></span>
<span id="cb69-2"><a href="#cb69-2" aria-hidden="true"></a>require <span class="st">'ddtrace'</span></span>
<span id="cb69-3"><a href="#cb69-3" aria-hidden="true"></a></span>
<span id="cb69-4"><a href="#cb69-4" aria-hidden="true"></a><span class="dt">Datadog</span>.configure <span class="kw">do</span> |c|</span>
<span id="cb69-5"><a href="#cb69-5" aria-hidden="true"></a>  c.tracing.instrument <span class="st">:redis</span> <span class="co"># Enabling integration instrumentation is still required</span></span>
<span id="cb69-6"><a href="#cb69-6" aria-hidden="true"></a><span class="kw">end</span></span>
<span id="cb69-7"><a href="#cb69-7" aria-hidden="true"></a></span>
<span id="cb69-8"><a href="#cb69-8" aria-hidden="true"></a>customer_cache = <span class="dt">Redis</span>.new(<span class="st">custom: </span>{ <span class="st">datadog: </span>{ <span class="st">service_name: 'custom-cache'</span> } })</span>
<span id="cb69-9"><a href="#cb69-9" aria-hidden="true"></a>invoice_cache = <span class="dt">Redis</span>.new(<span class="st">custom: </span>{ <span class="st">datadog: </span>{ <span class="st">service_name: 'invoice-cache'</span> } })</span>
<span id="cb69-10"><a href="#cb69-10" aria-hidden="true"></a></span>
<span id="cb69-11"><a href="#cb69-11" aria-hidden="true"></a><span class="co"># Traced call will belong to `customer-cache` service</span></span>
<span id="cb69-12"><a href="#cb69-12" aria-hidden="true"></a>customer_cache.get(...)</span>
<span id="cb69-13"><a href="#cb69-13" aria-hidden="true"></a><span class="co"># Traced call will belong to `invoice-cache` service</span></span>
<span id="cb69-14"><a href="#cb69-14" aria-hidden="true"></a>invoice_cache.get(...)</span></code></pre></div>
<p>With Redis version &lt; 5:</p>
<div class="sourceCode" id="cb70"><pre class="sourceCode ruby"><code class="sourceCode ruby"><span id="cb70-1"><a href="#cb70-1" aria-hidden="true"></a>require <span class="st">'redis'</span></span>
<span id="cb70-2"><a href="#cb70-2" aria-hidden="true"></a>require <span class="st">'ddtrace'</span></span>
<span id="cb70-3"><a href="#cb70-3" aria-hidden="true"></a></span>
<span id="cb70-4"><a href="#cb70-4" aria-hidden="true"></a><span class="dt">Datadog</span>.configure <span class="kw">do</span> |c|</span>
<span id="cb70-5"><a href="#cb70-5" aria-hidden="true"></a>  c.tracing.instrument <span class="st">:redis</span> <span class="co"># Enabling integration instrumentation is still required</span></span>
<span id="cb70-6"><a href="#cb70-6" aria-hidden="true"></a><span class="kw">end</span></span>
<span id="cb70-7"><a href="#cb70-7" aria-hidden="true"></a></span>
<span id="cb70-8"><a href="#cb70-8" aria-hidden="true"></a>customer_cache = <span class="dt">Redis</span>.new</span>
<span id="cb70-9"><a href="#cb70-9" aria-hidden="true"></a>invoice_cache = <span class="dt">Redis</span>.new</span>
<span id="cb70-10"><a href="#cb70-10" aria-hidden="true"></a></span>
<span id="cb70-11"><a href="#cb70-11" aria-hidden="true"></a><span class="dt">Datadog</span>.configure_onto(customer_cache, <span class="st">service_name: 'customer-cache'</span>)</span>
<span id="cb70-12"><a href="#cb70-12" aria-hidden="true"></a><span class="dt">Datadog</span>.configure_onto(invoice_cache, <span class="st">service_name: 'invoice-cache'</span>)</span>
<span id="cb70-13"><a href="#cb70-13" aria-hidden="true"></a></span>
<span id="cb70-14"><a href="#cb70-14" aria-hidden="true"></a><span class="co"># Traced call will belong to `customer-cache` service</span></span>
<span id="cb70-15"><a href="#cb70-15" aria-hidden="true"></a>customer_cache.get(...)</span>
<span id="cb70-16"><a href="#cb70-16" aria-hidden="true"></a><span class="co"># Traced call will belong to `invoice-cache` service</span></span>
<span id="cb70-17"><a href="#cb70-17" aria-hidden="true"></a>invoice_cache.get(...)</span></code></pre></div>
<p><strong>Configuring trace settings per connection</strong></p>
<p>You can configure trace settings per connection by using the <code>describes</code> option:</p>
<div class="sourceCode" id="cb71"><pre class="sourceCode ruby"><code class="sourceCode ruby"><span id="cb71-1"><a href="#cb71-1" aria-hidden="true"></a><span class="co"># Provide a `:describes` option with a connection key.</span></span>
<span id="cb71-2"><a href="#cb71-2" aria-hidden="true"></a><span class="co"># Any of the following keys are acceptable and equivalent to one another.</span></span>
<span id="cb71-3"><a href="#cb71-3" aria-hidden="true"></a><span class="co"># If a block is provided, it yields a Settings object that</span></span>
<span id="cb71-4"><a href="#cb71-4" aria-hidden="true"></a><span class="co"># accepts any of the configuration options listed above.</span></span>
<span id="cb71-5"><a href="#cb71-5" aria-hidden="true"></a></span>
<span id="cb71-6"><a href="#cb71-6" aria-hidden="true"></a><span class="dt">Datadog</span>.configure <span class="kw">do</span> |c|</span>
<span id="cb71-7"><a href="#cb71-7" aria-hidden="true"></a>  <span class="co"># The default configuration for any redis client</span></span>
<span id="cb71-8"><a href="#cb71-8" aria-hidden="true"></a>  c.tracing.instrument <span class="st">:redis</span>, <span class="st">service_name: 'redis-default'</span></span>
<span id="cb71-9"><a href="#cb71-9" aria-hidden="true"></a></span>
<span id="cb71-10"><a href="#cb71-10" aria-hidden="true"></a>  <span class="co"># The configuration matching a given unix socket.</span></span>
<span id="cb71-11"><a href="#cb71-11" aria-hidden="true"></a>  c.tracing.instrument <span class="st">:redis</span>, <span class="st">describes: </span>{ <span class="st">url: 'unix://path/to/file'</span> }, <span class="st">service_name: 'redis-unix'</span></span>
<span id="cb71-12"><a href="#cb71-12" aria-hidden="true"></a></span>
<span id="cb71-13"><a href="#cb71-13" aria-hidden="true"></a>  <span class="co"># For network connections, only these fields are considered during matching:</span></span>
<span id="cb71-14"><a href="#cb71-14" aria-hidden="true"></a>  <span class="co"># scheme, host, port, db</span></span>
<span id="cb71-15"><a href="#cb71-15" aria-hidden="true"></a>  <span class="co"># Other fields are ignored.</span></span>
<span id="cb71-16"><a href="#cb71-16" aria-hidden="true"></a></span>
<span id="cb71-17"><a href="#cb71-17" aria-hidden="true"></a>  <span class="co"># Network connection string</span></span>
<span id="cb71-18"><a href="#cb71-18" aria-hidden="true"></a>  c.tracing.instrument <span class="st">:redis</span>, <span class="st">describes: 'redis://127.0.0.1:6379/0'</span>, <span class="st">service_name: 'redis-connection-string'</span></span>
<span id="cb71-19"><a href="#cb71-19" aria-hidden="true"></a>  c.tracing.instrument <span class="st">:redis</span>, <span class="st">describes: </span>{ <span class="st">url: 'redis://127.0.0.1:6379/1'</span> }, <span class="st">service_name: 'redis-connection-url'</span></span>
<span id="cb71-20"><a href="#cb71-20" aria-hidden="true"></a>  <span class="co"># Network client hash</span></span>
<span id="cb71-21"><a href="#cb71-21" aria-hidden="true"></a>  c.tracing.instrument <span class="st">:redis</span>, <span class="st">describes: </span>{ <span class="st">host: 'my-host.com'</span>, <span class="st">port: </span><span class="dv">6379</span>, <span class="st">db: </span><span class="dv">1</span>, <span class="st">scheme: 'redis'</span> }, <span class="st">service_name: 'redis-connection-hash'</span></span>
<span id="cb71-22"><a href="#cb71-22" aria-hidden="true"></a>  <span class="co"># Only a subset of the connection hash</span></span>
<span id="cb71-23"><a href="#cb71-23" aria-hidden="true"></a>  c.tracing.instrument <span class="st">:redis</span>, <span class="st">describes: </span>{ <span class="st">host: </span><span class="dt">ENV</span>[<span class="st">'APP_CACHE_HOST'</span>], <span class="st">port: </span><span class="dt">ENV</span>[<span class="st">'APP_CACHE_PORT'</span>] }, <span class="st">service_name: 'redis-cache'</span></span>
<span id="cb71-24"><a href="#cb71-24" aria-hidden="true"></a>  c.tracing.instrument <span class="st">:redis</span>, <span class="st">describes: </span>{ <span class="st">host: </span><span class="dt">ENV</span>[<span class="st">'SIDEKIQ_CACHE_HOST'</span>] }, <span class="st">service_name: 'redis-sidekiq'</span></span>
<span id="cb71-25"><a href="#cb71-25" 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>
<h3 id="resque">Resque</h3>
<p>The Resque integration uses Resque hooks that wraps the <code>perform</code> method.</p>
<p>To add tracing to a Resque job:</p>
<div class="sourceCode" id="cb72"><pre class="sourceCode ruby"><code class="sourceCode ruby"><span id="cb72-1"><a href="#cb72-1" aria-hidden="true"></a>require <span class="st">'resque'</span></span>
<span id="cb72-2"><a href="#cb72-2" aria-hidden="true"></a>require <span class="st">'ddtrace'</span></span>
<span id="cb72-3"><a href="#cb72-3" aria-hidden="true"></a></span>
<span id="cb72-4"><a href="#cb72-4" aria-hidden="true"></a><span class="dt">Datadog</span>.configure <span class="kw">do</span> |c|</span>
<span id="cb72-5"><a href="#cb72-5" aria-hidden="true"></a>  c.tracing.instrument <span class="st">:resque</span>, **options</span>
<span id="cb72-6"><a href="#cb72-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: 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="rest-client">Rest Client</h3>
<p>The <code>rest-client</code> integration is available through the <code>ddtrace</code> middleware:</p>
<div class="sourceCode" id="cb73"><pre class="sourceCode ruby"><code class="sourceCode ruby"><span id="cb73-1"><a href="#cb73-1" aria-hidden="true"></a>require <span class="st">'rest_client'</span></span>
<span id="cb73-2"><a href="#cb73-2" aria-hidden="true"></a>require <span class="st">'ddtrace'</span></span>
<span id="cb73-3"><a href="#cb73-3" aria-hidden="true"></a></span>
<span id="cb73-4"><a href="#cb73-4" aria-hidden="true"></a><span class="dt">Datadog</span>.configure <span class="kw">do</span> |c|</span>
<span id="cb73-5"><a href="#cb73-5" aria-hidden="true"></a>  c.tracing.instrument <span class="st">:rest_client</span>, **options</span>
<span id="cb73-6"><a href="#cb73-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: 8%">
<col style="width: 13%">
<col style="width: 72%">
<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>service_name</code></td>
<td><code>DD_TRACE_REST_CLIENT_SERVICE_NAME</code></td>
<td>Name of application running the <code>rest_client</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>rest_client</code></td>
</tr>
<tr class="even">
<td><code>peer_service</code></td>
<td><code>DD_TRACE_REST_CLIENT_PEER_SERVICE</code></td>
<td>Name of external service the application connects to</td>
<td><code>nil</code></td>
</tr>
<tr class="odd">
<td><code>distributed_tracing</code></td>
<td></td>
<td>Enables <a href="#distributed-tracing">distributed tracing</a>
</td>
<td><code>true</code></td>
</tr>
<tr class="even">
<td><code>split_by_domain</code></td>
<td></td>
<td>Uses the request domain as the service name when set to <code>true</code>.</td>
<td><code>false</code></td>
</tr>
</tbody>
</table>
<h3 id="roda">Roda</h3>
<p>The Roda integration traces requests.</p>
<p>The <strong>Roda</strong> integration can be enabled through <code>Datadog.configure</code>. It is recommended to use this integration with <strong>Rack</strong> through <code>use Datadog::Tracing::Contrib::Rack::TraceMiddleware</code> for distributed tracing.</p>
<div class="sourceCode" id="cb74"><pre class="sourceCode ruby"><code class="sourceCode ruby"><span id="cb74-1"><a href="#cb74-1" aria-hidden="true"></a>require <span class="st">"roda"</span></span>
<span id="cb74-2"><a href="#cb74-2" aria-hidden="true"></a>require <span class="st">"ddtrace"</span></span>
<span id="cb74-3"><a href="#cb74-3" aria-hidden="true"></a></span>
<span id="cb74-4"><a href="#cb74-4" aria-hidden="true"></a><span class="kw">class</span> <span class="dt">SampleApp</span> &lt; <span class="dt">Roda</span></span>
<span id="cb74-5"><a href="#cb74-5" aria-hidden="true"></a>  use <span class="dt">Datadog</span>::<span class="dt">Tracing</span>::<span class="dt">Contrib</span>::<span class="dt">Rack</span>::<span class="dt">TraceMiddleware</span></span>
<span id="cb74-6"><a href="#cb74-6" aria-hidden="true"></a></span>
<span id="cb74-7"><a href="#cb74-7" aria-hidden="true"></a>  <span class="dt">Datadog</span>.configure <span class="kw">do</span> |c|</span>
<span id="cb74-8"><a href="#cb74-8" aria-hidden="true"></a>    c.tracing.instrument <span class="st">:roda</span>, **options</span>
<span id="cb74-9"><a href="#cb74-9" aria-hidden="true"></a>  <span class="kw">end</span></span>
<span id="cb74-10"><a href="#cb74-10" aria-hidden="true"></a></span>
<span id="cb74-11"><a href="#cb74-11" aria-hidden="true"></a>  route <span class="kw">do</span> |r|</span>
<span id="cb74-12"><a href="#cb74-12" aria-hidden="true"></a>    r.root <span class="kw">do</span></span>
<span id="cb74-13"><a href="#cb74-13" aria-hidden="true"></a>      r.get <span class="kw">do</span></span>
<span id="cb74-14"><a href="#cb74-14" aria-hidden="true"></a>        <span class="st">'Hello World!'</span></span>
<span id="cb74-15"><a href="#cb74-15" aria-hidden="true"></a>      <span class="kw">end</span></span>
<span id="cb74-16"><a href="#cb74-16" aria-hidden="true"></a>    <span class="kw">end</span></span>
<span id="cb74-17"><a href="#cb74-17" aria-hidden="true"></a>  <span class="kw">end</span></span>
<span id="cb74-18"><a href="#cb74-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>
<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>Service name for <code>roda</code> instrumentation.</td>
<td><code>'nil'</code></td>
</tr>
</tbody>
</table>
<h3 id="rspec">RSpec</h3>
<p>RSpec integration will trace all executions of example groups and examples when using <code>rspec</code> test framework.</p>
<p>To activate your integration, use the <code>Datadog.configure</code> method:</p>
<div class="sourceCode" id="cb75"><pre class="sourceCode ruby"><code class="sourceCode ruby"><span id="cb75-1"><a href="#cb75-1" aria-hidden="true"></a>require <span class="st">'rspec'</span></span>
<span id="cb75-2"><a href="#cb75-2" aria-hidden="true"></a>require <span class="st">'ddtrace'</span></span>
<span id="cb75-3"><a href="#cb75-3" aria-hidden="true"></a></span>
<span id="cb75-4"><a href="#cb75-4" aria-hidden="true"></a><span class="co"># Configure default RSpec integration</span></span>
<span id="cb75-5"><a href="#cb75-5" aria-hidden="true"></a><span class="dt">Datadog</span>.configure <span class="kw">do</span> |c|</span>
<span id="cb75-6"><a href="#cb75-6" aria-hidden="true"></a>  c.ci.instrument <span class="st">:rspec</span>, **options</span>
<span id="cb75-7"><a href="#cb75-7" 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 RSpec 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>rspec</code> instrumentation.</td>
<td><code>'rspec'</code></td>
</tr>
<tr class="odd">
<td><code>operation_name</code></td>
<td>Operation name used for <code>rspec</code> instrumentation. Useful if you want rename automatic trace metrics e.g. <code>trace.#{operation_name}.errors</code>.</td>
<td><code>'rspec.example'</code></td>
</tr>
</tbody>
</table>
<h3 id="sequel">Sequel</h3>
<p>The Sequel integration traces queries made to your database.</p>
<div class="sourceCode" id="cb76"><pre class="sourceCode ruby"><code class="sourceCode ruby"><span id="cb76-1"><a href="#cb76-1" aria-hidden="true"></a>require <span class="st">'sequel'</span></span>
<span id="cb76-2"><a href="#cb76-2" aria-hidden="true"></a>require <span class="st">'ddtrace'</span></span>
<span id="cb76-3"><a href="#cb76-3" aria-hidden="true"></a></span>
<span id="cb76-4"><a href="#cb76-4" aria-hidden="true"></a><span class="co"># Connect to database</span></span>
<span id="cb76-5"><a href="#cb76-5" aria-hidden="true"></a>database = <span class="dt">Sequel</span>.sqlite</span>
<span id="cb76-6"><a href="#cb76-6" aria-hidden="true"></a></span>
<span id="cb76-7"><a href="#cb76-7" aria-hidden="true"></a><span class="co"># Create a table</span></span>
<span id="cb76-8"><a href="#cb76-8" aria-hidden="true"></a>database.create_table <span class="st">:articles</span> <span class="kw">do</span></span>
<span id="cb76-9"><a href="#cb76-9" aria-hidden="true"></a>  primary_key <span class="st">:id</span></span>
<span id="cb76-10"><a href="#cb76-10" aria-hidden="true"></a>  <span class="dt">String</span> <span class="st">:name</span></span>
<span id="cb76-11"><a href="#cb76-11" aria-hidden="true"></a><span class="kw">end</span></span>
<span id="cb76-12"><a href="#cb76-12" aria-hidden="true"></a></span>
<span id="cb76-13"><a href="#cb76-13" aria-hidden="true"></a><span class="dt">Datadog</span>.configure <span class="kw">do</span> |c|</span>
<span id="cb76-14"><a href="#cb76-14" aria-hidden="true"></a>  c.tracing.instrument <span class="st">:sequel</span>, **options</span>
<span id="cb76-15"><a href="#cb76-15" aria-hidden="true"></a><span class="kw">end</span></span>
<span id="cb76-16"><a href="#cb76-16" aria-hidden="true"></a></span>
<span id="cb76-17"><a href="#cb76-17" aria-hidden="true"></a><span class="co"># Perform a query</span></span>
<span id="cb76-18"><a href="#cb76-18" aria-hidden="true"></a>articles = database[<span class="st">:articles</span>]</span>
<span id="cb76-19"><a href="#cb76-19" aria-hidden="true"></a>articles.all</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>service_name</code></td>
<td>Service name for <code>sequel</code> instrumentation</td>
<td>Name of database adapter (e.g. <code>'mysql2'</code>)</td>
</tr>
</tbody>
</table>
<p><strong>Configuring databases to use different settings</strong></p>
<p>If you use multiple databases with Sequel, you can give each of them different settings by configuring their respective <code>Sequel::Database</code> objects:</p>
<div class="sourceCode" id="cb77"><pre class="sourceCode ruby"><code class="sourceCode ruby"><span id="cb77-1"><a href="#cb77-1" aria-hidden="true"></a>sqlite_database = <span class="dt">Sequel</span>.sqlite</span>
<span id="cb77-2"><a href="#cb77-2" aria-hidden="true"></a>postgres_database = <span class="dt">Sequel</span>.connect(<span class="st">'postgres://user:password@host:port/database_name'</span>)</span>
<span id="cb77-3"><a href="#cb77-3" aria-hidden="true"></a></span>
<span id="cb77-4"><a href="#cb77-4" aria-hidden="true"></a><span class="co"># Configure each database with different service names</span></span>
<span id="cb77-5"><a href="#cb77-5" aria-hidden="true"></a><span class="dt">Datadog</span>.configure_onto(sqlite_database, <span class="st">service_name: 'my-sqlite-db'</span>)</span>
<span id="cb77-6"><a href="#cb77-6" aria-hidden="true"></a><span class="dt">Datadog</span>.configure_onto(postgres_database, <span class="st">service_name: 'my-postgres-db'</span>)</span></code></pre></div>
<h3 id="shoryuken">Shoryuken</h3>
<p>The Shoryuken integration is a server-side middleware which will trace job executions.</p>
<p>You can enable it through <code>Datadog.configure</code>:</p>
<div class="sourceCode" id="cb78"><pre class="sourceCode ruby"><code class="sourceCode ruby"><span id="cb78-1"><a href="#cb78-1" aria-hidden="true"></a>require <span class="st">'ddtrace'</span></span>
<span id="cb78-2"><a href="#cb78-2" aria-hidden="true"></a></span>
<span id="cb78-3"><a href="#cb78-3" aria-hidden="true"></a><span class="dt">Datadog</span>.configure <span class="kw">do</span> |c|</span>
<span id="cb78-4"><a href="#cb78-4" aria-hidden="true"></a>  c.tracing.instrument <span class="st">:shoryuken</span>, **options</span>
<span id="cb78-5"><a href="#cb78-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>tag_body</code></td>
<td>Tag spans with the SQS message body <code>true</code> or <code>false</code>
</td>
<td><code>false</code></td>
</tr>
<tr class="even">
<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="sidekiq">Sidekiq</h3>
<p>The Sidekiq integration is a client-side &amp; server-side middleware which will trace job queuing and executions respectively.</p>
<p>You can enable it through <code>Datadog.configure</code>:</p>
<div class="sourceCode" id="cb79"><pre class="sourceCode ruby"><code class="sourceCode ruby"><span id="cb79-1"><a href="#cb79-1" aria-hidden="true"></a>require <span class="st">'ddtrace'</span></span>
<span id="cb79-2"><a href="#cb79-2" aria-hidden="true"></a></span>
<span id="cb79-3"><a href="#cb79-3" aria-hidden="true"></a><span class="dt">Datadog</span>.configure <span class="kw">do</span> |c|</span>
<span id="cb79-4"><a href="#cb79-4" aria-hidden="true"></a>  c.tracing.instrument <span class="st">:sidekiq</span>, **options</span>
<span id="cb79-5"><a href="#cb79-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>distributed_tracing</code></td>
<td>Enabling <a href="#distributed-tracing">distributed tracing</a> creates a parent-child relationship between the <code>sidekiq.push</code> span and the <code>sidekiq.job</code> span. <br><br><strong>Important</strong>: <em>Enabling distributed_tracing for asynchronous processing can result in drastic changes in your trace graph. Such cases include long running jobs, retried jobs, and jobs scheduled in the far future. Make sure to inspect your traces after enabling this feature.</em>
</td>
<td><code>false</code></td>
</tr>
<tr class="even">
<td><code>tag_args</code></td>
<td>Enable tagging of job arguments. <code>true</code> for on, <code>false</code> for off.</td>
<td><code>false</code></td>
</tr>
<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>
<tr class="even">
<td><code>quantize</code></td>
<td>Hash containing options for quantization of job arguments.</td>
<td><code>{}</code></td>
</tr>
</tbody>
</table>
<h3 id="sinatra">Sinatra</h3>
<p>The Sinatra integration traces requests and template rendering.</p>
<p>To start using the tracing client, make sure you import <code>ddtrace</code> and <code>instrument :sinatra</code> after either <code>sinatra</code> or <code>sinatra/base</code>, and before you define your application/routes:</p>
<h4 id="classic-application">Classic application</h4>
<div class="sourceCode" id="cb80"><pre class="sourceCode ruby"><code class="sourceCode ruby"><span id="cb80-1"><a href="#cb80-1" aria-hidden="true"></a>require <span class="st">'sinatra'</span></span>
<span id="cb80-2"><a href="#cb80-2" aria-hidden="true"></a>require <span class="st">'ddtrace'</span></span>
<span id="cb80-3"><a href="#cb80-3" aria-hidden="true"></a></span>
<span id="cb80-4"><a href="#cb80-4" aria-hidden="true"></a><span class="dt">Datadog</span>.configure <span class="kw">do</span> |c|</span>
<span id="cb80-5"><a href="#cb80-5" aria-hidden="true"></a>  c.tracing.instrument <span class="st">:sinatra</span>, **options</span>
<span id="cb80-6"><a href="#cb80-6" aria-hidden="true"></a><span class="kw">end</span></span>
<span id="cb80-7"><a href="#cb80-7" aria-hidden="true"></a></span>
<span id="cb80-8"><a href="#cb80-8" aria-hidden="true"></a>get <span class="ch">'/'</span> <span class="kw">do</span></span>
<span id="cb80-9"><a href="#cb80-9" aria-hidden="true"></a>  <span class="st">'Hello world!'</span></span>
<span id="cb80-10"><a href="#cb80-10" aria-hidden="true"></a><span class="kw">end</span></span></code></pre></div>
<h4 id="modular-application">Modular application</h4>
<div class="sourceCode" id="cb81"><pre class="sourceCode ruby"><code class="sourceCode ruby"><span id="cb81-1"><a href="#cb81-1" aria-hidden="true"></a>require <span class="st">'sinatra/base'</span></span>
<span id="cb81-2"><a href="#cb81-2" aria-hidden="true"></a>require <span class="st">'ddtrace'</span></span>
<span id="cb81-3"><a href="#cb81-3" aria-hidden="true"></a></span>
<span id="cb81-4"><a href="#cb81-4" aria-hidden="true"></a><span class="dt">Datadog</span>.configure <span class="kw">do</span> |c|</span>
<span id="cb81-5"><a href="#cb81-5" aria-hidden="true"></a>  c.tracing.instrument <span class="st">:sinatra</span>, **options</span>
<span id="cb81-6"><a href="#cb81-6" aria-hidden="true"></a><span class="kw">end</span></span>
<span id="cb81-7"><a href="#cb81-7" aria-hidden="true"></a></span>
<span id="cb81-8"><a href="#cb81-8" aria-hidden="true"></a><span class="kw">class</span> <span class="dt">NestedApp</span> &lt; <span class="dt">Sinatra</span>::<span class="dt">Base</span></span>
<span id="cb81-9"><a href="#cb81-9" aria-hidden="true"></a>  get <span class="st">'/nested'</span> <span class="kw">do</span></span>
<span id="cb81-10"><a href="#cb81-10" aria-hidden="true"></a>    <span class="st">'Hello from nested app!'</span></span>
<span id="cb81-11"><a href="#cb81-11" aria-hidden="true"></a>  <span class="kw">end</span></span>
<span id="cb81-12"><a href="#cb81-12" aria-hidden="true"></a><span class="kw">end</span></span>
<span id="cb81-13"><a href="#cb81-13" aria-hidden="true"></a></span>
<span id="cb81-14"><a href="#cb81-14" aria-hidden="true"></a><span class="kw">class</span> <span class="dt">App</span> &lt; <span class="dt">Sinatra</span>::<span class="dt">Base</span></span>
<span id="cb81-15"><a href="#cb81-15" aria-hidden="true"></a>  use <span class="dt">NestedApp</span></span>
<span id="cb81-16"><a href="#cb81-16" aria-hidden="true"></a></span>
<span id="cb81-17"><a href="#cb81-17" aria-hidden="true"></a>  get <span class="ch">'/'</span> <span class="kw">do</span></span>
<span id="cb81-18"><a href="#cb81-18" aria-hidden="true"></a>    <span class="st">'Hello world!'</span></span>
<span id="cb81-19"><a href="#cb81-19" aria-hidden="true"></a>  <span class="kw">end</span></span>
<span id="cb81-20"><a href="#cb81-20" aria-hidden="true"></a><span class="kw">end</span></span></code></pre></div>
<h4 id="instrumentation-options">Instrumentation options</h4>
<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>distributed_tracing</code></td>
<td>Enables <a href="#distributed-tracing">distributed tracing</a> so that this service trace is connected with a trace of another service if tracing headers are received</td>
<td><code>true</code></td>
</tr>
<tr class="even">
<td><code>headers</code></td>
<td>Hash of HTTP request or response headers to add as tags to the <code>sinatra.request</code>. Accepts <code>request</code> and <code>response</code> keys with Array values e.g. <code>['Last-Modified']</code>. Adds <code>http.request.headers.*</code> and <code>http.response.headers.*</code> tags respectively. This option overrides the global <code>DD_TRACE_HEADER_TAGS</code>, see <a href="https://docs.datadoghq.com/tracing/configure_data_security/#applying-header-tags-to-root-spans">Applying header tags to root spans</a> for more information.</td>
<td><code>{ response: ['Content-Type', 'X-Request-ID'] }</code></td>
</tr>
<tr class="odd">
<td><code>resource_script_names</code></td>
<td>Prepend resource names with script name</td>
<td><code>false</code></td>
</tr>
</tbody>
</table>
<h3 id="sneakers">Sneakers</h3>
<p>The Sneakers integration is a server-side middleware which will trace job executions.</p>
<p>You can enable it through <code>Datadog.configure</code>:</p>
<div class="sourceCode" id="cb82"><pre class="sourceCode ruby"><code class="sourceCode ruby"><span id="cb82-1"><a href="#cb82-1" aria-hidden="true"></a>require <span class="st">'ddtrace'</span></span>
<span id="cb82-2"><a href="#cb82-2" aria-hidden="true"></a></span>
<span id="cb82-3"><a href="#cb82-3" aria-hidden="true"></a><span class="dt">Datadog</span>.configure <span class="kw">do</span> |c|</span>
<span id="cb82-4"><a href="#cb82-4" aria-hidden="true"></a>  c.tracing.instrument <span class="st">:sneakers</span>, **options</span>
<span id="cb82-5"><a href="#cb82-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>enabled</code></td>
<td>Defines whether Sneakers 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>tag_body</code></td>
<td>Enable tagging of job message. <code>true</code> for on, <code>false</code> for off.</td>
<td><code>false</code></td>
</tr>
<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="stripe">Stripe</h3>
<p>The Stripe integration traces Stripe API requests.</p>
<p>You can enable it through <code>Datadog.configure</code>:</p>
<div class="sourceCode" id="cb83"><pre class="sourceCode ruby"><code class="sourceCode ruby"><span id="cb83-1"><a href="#cb83-1" aria-hidden="true"></a>require <span class="st">'ddtrace'</span></span>
<span id="cb83-2"><a href="#cb83-2" aria-hidden="true"></a></span>
<span id="cb83-3"><a href="#cb83-3" aria-hidden="true"></a><span class="dt">Datadog</span>.configure <span class="kw">do</span> |c|</span>
<span id="cb83-4"><a href="#cb83-4" aria-hidden="true"></a>  c.tracing.instrument <span class="st">:stripe</span>, **options</span>
<span id="cb83-5"><a href="#cb83-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>enabled</code></td>
<td>Defines whether Stripe should be traced. Useful for temporarily disabling tracing. <code>true</code> or <code>false</code>
</td>
<td><code>true</code></td>
</tr>
</tbody>
</table>
<h3 id="sucker-punch">Sucker Punch</h3>
<p>The <code>sucker_punch</code> integration traces all scheduled jobs:</p>
<div class="sourceCode" id="cb84"><pre class="sourceCode ruby"><code class="sourceCode ruby"><span id="cb84-1"><a href="#cb84-1" aria-hidden="true"></a>require <span class="st">'ddtrace'</span></span>
<span id="cb84-2"><a href="#cb84-2" aria-hidden="true"></a></span>
<span id="cb84-3"><a href="#cb84-3" aria-hidden="true"></a><span class="dt">Datadog</span>.configure <span class="kw">do</span> |c|</span>
<span id="cb84-4"><a href="#cb84-4" aria-hidden="true"></a>  c.tracing.instrument <span class="st">:sucker_punch</span></span>
<span id="cb84-5"><a href="#cb84-5" aria-hidden="true"></a><span class="kw">end</span></span>
<span id="cb84-6"><a href="#cb84-6" aria-hidden="true"></a></span>
<span id="cb84-7"><a href="#cb84-7" aria-hidden="true"></a><span class="co"># Execution of this job is traced</span></span>
<span id="cb84-8"><a href="#cb84-8" aria-hidden="true"></a><span class="dt">LogJob</span>.perform_async(<span class="st">'login'</span>)</span></code></pre></div>
<h3 id="trilogy">Trilogy</h3>
<p>The trilogy integration traces any SQL command sent through the <code>trilogy</code> gem.</p>
<div class="sourceCode" id="cb85"><pre class="sourceCode ruby"><code class="sourceCode ruby"><span id="cb85-1"><a href="#cb85-1" aria-hidden="true"></a>require <span class="st">'trilogy'</span></span>
<span id="cb85-2"><a href="#cb85-2" aria-hidden="true"></a>require <span class="st">'ddtrace'</span></span>
<span id="cb85-3"><a href="#cb85-3" aria-hidden="true"></a></span>
<span id="cb85-4"><a href="#cb85-4" aria-hidden="true"></a><span class="dt">Datadog</span>.configure <span class="kw">do</span> |c|</span>
<span id="cb85-5"><a href="#cb85-5" aria-hidden="true"></a>  c.tracing.instrument <span class="st">:trilogy</span>, **options</span>
<span id="cb85-6"><a href="#cb85-6" aria-hidden="true"></a><span class="kw">end</span></span>
<span id="cb85-7"><a href="#cb85-7" aria-hidden="true"></a></span>
<span id="cb85-8"><a href="#cb85-8" aria-hidden="true"></a>client = <span class="dt">Trilogy</span>.new(<span class="st">host: "localhost"</span>, <span class="st">username: "root"</span>)</span>
<span id="cb85-9"><a href="#cb85-9" aria-hidden="true"></a>client.query(<span class="st">"SELECT * FROM users WHERE group='x'"</span>)</span></code></pre></div>
<p><code>options</code> are the following keyword arguments:</p>
<table>
<colgroup>
<col style="width: 8%">
<col style="width: 12%">
<col style="width: 73%">
<col style="width: 4%">
</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_TRILOGY_SERVICE_NAME</code></td>
<td>Name of application running the <code>trilogy</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>trilogy</code></td>
</tr>
<tr class="even">
<td><code>peer_service</code></td>
<td><code>DD_TRACE_TRILOGY_PEER_SERVICE</code></td>
<td>Name of external service the application connects to</td>
<td><code>nil</code></td>
</tr>
</tbody>
</table>
<h2 id="additional-configuration">Additional configuration</h2>
<p>To change the default behavior of <code>ddtrace</code>, you can use, in order of priority, with 1 being the highest:</p>
<ol type="1">
<li><p><a href="https://docs.datadoghq.com/agent/remote_config">Remote Configuration</a>.</p></li>
<li>
<p>Options set inside a <code>Datadog.configure</code> block, e.g.: ```ruby Datadog.configure do |c| c.service = ‘billing-api’ c.env = ENV[‘RACK_ENV’]</p>
<p>c.tracing.report_hostname = true c.tracing.test_mode.enabled = (ENV[‘RACK_ENV’] == ‘test’) end ```</p>
</li>
<li><p>Environment variables.</p></li>
</ol>
<p><strong>If a higher priority value is set for an option, setting that option with a lower priority value will not change its effective value.</strong></p>
<p>For example, if <code>tracing.sampling.default_rate</code> is configured by <a href="#remote-configuration">Remote Configuration</a>, changing its value through the <code>Datadog.configure</code> block will have no effect.</p>
<p><strong>Available configuration options:</strong></p>
<table>
<colgroup>
<col style="width: 7%">
<col style="width: 7%">
<col style="width: 4%">
<col style="width: 79%">
</colgroup>
<thead>
<tr class="header">
<th>Setting</th>
<th>Env Var</th>
<th>Default</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr class="odd">
<td><strong>Global</strong></td>
<td></td>
<td></td>
<td></td>
</tr>
<tr class="even">
<td><code>agent.host</code></td>
<td><code>DD_AGENT_HOST</code></td>
<td><code>127.0.0.1</code></td>
<td>Hostname of Agent to where trace data will be sent.</td>
</tr>
<tr class="odd">
<td><code>agent.port</code></td>
<td><code>DD_TRACE_AGENT_PORT</code></td>
<td><code>8126</code></td>
<td>Port of Agent host to where trace data will be sent. If the <a href="#configuring-trace-data-ingestion">Agent configuration</a> sets <code>receiver_port</code> or <code>DD_APM_RECEIVER_PORT</code> to something other than the default <code>8126</code>, then <code>DD_TRACE_AGENT_PORT</code> or <code>DD_TRACE_AGENT_URL</code> must match it.</td>
</tr>
<tr class="even">
<td></td>
<td><code>DD_TRACE_AGENT_URL</code></td>
<td><code>nil</code></td>
<td>Sets the URL endpoint where traces are sent. Has priority over <code>agent.host</code> and <code>agent.port</code>. If the <a href="#configuring-trace-data-ingestion">Agent configuration</a> sets <code>receiver_port</code> or <code>DD_APM_RECEIVER_PORT</code> to something other than the default <code>8126</code>, then <code>DD_TRACE_AGENT_PORT</code> or <code>DD_TRACE_AGENT_URL</code> must match it.</td>
</tr>
<tr class="odd">
<td><code>diagnostics.debug</code></td>
<td><code>DD_TRACE_DEBUG</code></td>
<td><code>false</code></td>
<td>Enables or disables debug mode. Prints verbose logs. <strong>NOT recommended for production or other sensitive environments.</strong> See <a href="#debugging-and-diagnostics">Debugging and diagnostics</a> for more details.</td>
</tr>
<tr class="even">
<td><code>diagnostics.startup_logs.enabled</code></td>
<td><code>DD_TRACE_STARTUP_LOGS</code></td>
<td><code>nil</code></td>
<td>Prints startup configuration and diagnostics to log. For assessing state of tracing at application startup. See <a href="#debugging-and-diagnostics">Debugging and diagnostics</a> for more details.</td>
</tr>
<tr class="odd">
<td><code>env</code></td>
<td><code>DD_ENV</code></td>
<td><code>nil</code></td>
<td>Your application environment. (e.g. <code>production</code>, <code>staging</code>, etc.) This value is set as a tag on all traces.</td>
</tr>
<tr class="even">
<td><code>service</code></td>
<td><code>DD_SERVICE</code></td>
<td><em>Ruby filename</em></td>
<td>Your application’s default service name. (e.g. <code>billing-api</code>) This value is set as a tag on all traces.</td>
</tr>
<tr class="odd">
<td><code>tags</code></td>
<td><code>DD_TAGS</code></td>
<td><code>nil</code></td>
<td>Custom tags in value pairs separated by <code>,</code> (e.g. <code>layer:api,team:intake</code>) These tags are set on all traces. See <a href="#environment-and-tags">Environment and tags</a> for more details.</td>
</tr>
<tr class="even">
<td><code>time_now_provider</code></td>
<td></td>
<td><code>-&gt;{ Time.now }</code></td>
<td>Changes how time is retrieved. See <a href="#setting-the-time-provider">Setting the time provider</a> for more details.</td>
</tr>
<tr class="odd">
<td><code>version</code></td>
<td><code>DD_VERSION</code></td>
<td><code>nil</code></td>
<td>Your application version (e.g. <code>2.5</code>, <code>202003181415</code>, <code>1.3-alpha</code>, etc.) This value is set as a tag on all traces.</td>
</tr>
<tr class="even">
<td><code>telemetry.enabled</code></td>
<td><code>DD_INSTRUMENTATION_TELEMETRY_ENABLED</code></td>
<td><code>true</code></td>
<td>Allows you to enable sending telemetry data to Datadog. Can be disabled, as documented <a href="https://docs.datadoghq.com/tracing/configure_data_security/#telemetry-collection">here</a>.</td>
</tr>
<tr class="odd">
<td><strong>Tracing</strong></td>
<td></td>
<td></td>
<td></td>
</tr>
<tr class="even">
<td><code>tracing.analytics.enabled</code></td>
<td><code>DD_TRACE_ANALYTICS_ENABLED</code></td>
<td><code>nil</code></td>
<td>Enables or disables trace analytics. See <a href="#sampling">Sampling</a> for more details.</td>
</tr>
<tr class="odd">
<td><code>tracing.contrib.peer_service_mapping</code></td>
<td><code>DD_TRACE_PEER_SERVICE_MAPPING</code></td>
<td><code>nil</code></td>
<td>Defines remapping of <code>peer.service</code> tag across all instrumentation. Provide a list of <code>old_value1:new_value1, old_value2:new_value2, ...</code>
</td>
</tr>
<tr class="even">
<td><code>tracing.contrib.global_default_service_name.enabled</code></td>
<td><code>DD_TRACE_REMOVE_INTEGRATION_SERVICE_NAMES_ENABLED</code></td>
<td><code>false</code></td>
<td>Changes the default value for <code>service_name</code> to the application service name across all instrumentation</td>
</tr>
<tr class="odd">
<td><code>tracing.distributed_tracing.propagation_extract_first</code></td>
<td><code>DD_TRACE_PROPAGATION_EXTRACT_FIRST</code></td>
<td><code>false</code></td>
<td>Exit immediately on the first valid propagation format detected. See <a href="#distributed-tracing">Distributed Tracing</a> for more details.</td>
</tr>
<tr class="even">
<td><code>tracing.distributed_tracing.propagation_extract_style</code></td>
<td><code>DD_TRACE_PROPAGATION_STYLE_EXTRACT</code></td>
<td><code>['Datadog','tracecontext']</code></td>
<td>Distributed tracing propagation formats to extract. Overrides <code>DD_TRACE_PROPAGATION_STYLE</code>. See <a href="#distributed-tracing">Distributed Tracing</a> for more details.</td>
</tr>
<tr class="odd">
<td><code>tracing.distributed_tracing.propagation_inject_style</code></td>
<td><code>DD_TRACE_PROPAGATION_STYLE_INJECT</code></td>
<td><code>['Datadog','tracecontext']</code></td>
<td>Distributed tracing propagation formats to inject. Overrides <code>DD_TRACE_PROPAGATION_STYLE</code>. See <a href="#distributed-tracing">Distributed Tracing</a> for more details.</td>
</tr>
<tr class="even">
<td><code>tracing.distributed_tracing.propagation_style</code></td>
<td><code>DD_TRACE_PROPAGATION_STYLE</code></td>
<td><code>nil</code></td>
<td>Distributed tracing propagation formats to extract and inject. See <a href="#distributed-tracing">Distributed Tracing</a> for more details.</td>
</tr>
<tr class="odd">
<td><code>tracing.enabled</code></td>
<td><code>DD_TRACE_ENABLED</code></td>
<td><code>true</code></td>
<td>Enables or disables tracing. If set to <code>false</code> instrumentation will still run, but no traces are sent to the trace agent.</td>
</tr>
<tr class="even">
<td><code>tracing.header_tags</code></td>
<td><code>DD_TRACE_HEADER_TAGS</code></td>
<td><code>nil</code></td>
<td>Record HTTP headers as span tags. See <a href="https://docs.datadoghq.com/tracing/configure_data_security/#applying-header-tags-to-root-spans">Applying header tags to root spans</a> for more information.</td>
</tr>
<tr class="odd">
<td><code>tracing.instrument(&lt;integration-name&gt;, &lt;options...&gt;)</code></td>
<td></td>
<td></td>
<td>Activates instrumentation for a specific library. See <a href="#integration-instrumentation">Integration instrumentation</a> for more details.</td>
</tr>
<tr class="even">
<td><code>tracing.log_injection</code></td>
<td><code>DD_LOGS_INJECTION</code></td>
<td><code>true</code></td>
<td>Injects <a href="#trace-correlation">Trace Correlation</a> information into Rails logs if present. Supports the default logger (<code>ActiveSupport::TaggedLogging</code>), <code>lograge</code>, and <code>semantic_logger</code>.</td>
</tr>
<tr class="odd">
<td><code>tracing.partial_flush.enabled</code></td>
<td></td>
<td><code>false</code></td>
<td>Enables or disables partial flushing. Partial flushing submits completed portions of a trace to the agent. Used when tracing instruments long running tasks (e.g. jobs) with many spans.</td>
</tr>
<tr class="even">
<td><code>tracing.partial_flush.min_spans_threshold</code></td>
<td></td>
<td><code>500</code></td>
<td>The number of spans that must be completed in a trace before partial flushing submits those completed spans.</td>
</tr>
<tr class="odd">
<td><code>tracing.sampler</code></td>
<td></td>
<td><code>nil</code></td>
<td>Advanced usage only. Sets a custom <code>Datadog::Tracing::Sampling::Sampler</code> instance. If provided, the tracer will use this sampler to determine sampling behavior. See <a href="#application-side-sampling">Application-side sampling</a> for details.</td>
</tr>
<tr class="even">
<td><code>tracing.sampling.default_rate</code></td>
<td><code>DD_TRACE_SAMPLE_RATE</code></td>
<td><code>nil</code></td>
<td>Sets the trace sampling rate between <code>0.0</code> (0%) and <code>1.0</code> (100%). See <a href="#application-side-sampling">Application-side sampling</a> for details.</td>
</tr>
<tr class="odd">
<td><code>tracing.sampling.rate_limit</code></td>
<td><code>DD_TRACE_RATE_LIMIT</code></td>
<td>
<code>100</code> (per second)</td>
<td>Sets a maximum number of traces per second to sample. Set a rate limit to avoid the ingestion volume overages in the case of traffic spikes.</td>
</tr>
<tr class="even">
<td><code>tracing.sampling.rules</code></td>
<td><code>DD_TRACE_SAMPLING_RULES</code></td>
<td><code>nil</code></td>
<td>Sets trace-level sampling rules, matching against the local root span. The format is a <code>String</code> with JSON, containing an Array of Objects. Each Object must have a float attribute <code>sample_rate</code> (between 0.0 and 1.0, inclusive), and optionally <code>name</code> and <code>service</code> string attributes. <code>name</code> and <code>service</code> control to which traces this sampling rule applies; if both are absent, then this rule applies to all traces. Rules are evaluted in order of declartion in the array; only the first to match is applied. If none apply, then <code>tracing.sampling.default_rate</code> is applied.</td>
</tr>
<tr class="odd">
<td><code>tracing.sampling.span_rules</code></td>
<td>
<code>DD_SPAN_SAMPLING_RULES</code>,<code>ENV_SPAN_SAMPLING_RULES_FILE</code>
</td>
<td><code>nil</code></td>
<td>Sets <a href="#single-span-sampling">Single Span Sampling</a> rules. These rules allow you to keep spans even when their respective traces are dropped.</td>
</tr>
<tr class="even">
<td><code>tracing.trace_id_128_bit_generation_enabled</code></td>
<td><code>DD_TRACE_128_BIT_TRACEID_GENERATION_ENABLED</code></td>
<td><code>true</code></td>
<td>
<code>true</code> to generate 128 bits trace ID and <code>false</code> to generate 64 bits trace ID</td>
</tr>
<tr class="odd">
<td><code>tracing.report_hostname</code></td>
<td><code>DD_TRACE_REPORT_HOSTNAME</code></td>
<td><code>false</code></td>
<td>Adds hostname tag to traces.</td>
</tr>
<tr class="even">
<td><code>tracing.test_mode.enabled</code></td>
<td><code>DD_TRACE_TEST_MODE_ENABLED</code></td>
<td><code>false</code></td>
<td>Enables or disables test mode, for use of tracing in test suites.</td>
</tr>
<tr class="odd">
<td><code>tracing.test_mode.trace_flush</code></td>
<td></td>
<td><code>nil</code></td>
<td>Object that determines trace flushing behavior.</td>
</tr>
</tbody>
</table>
<h4 id="custom-logging">Custom logging</h4>
<p>By default, all logs are processed by the default Ruby logger. When using Rails, you should see the messages in your application log file.</p>
<p>Datadog client log messages are marked with <code>[ddtrace]</code> so you should be able to isolate them from other messages.</p>
<p>Additionally, it is possible to override the default logger and replace it by a custom one. This is done using the <code>log</code> setting.</p>
<div class="sourceCode" id="cb86"><pre class="sourceCode ruby"><code class="sourceCode ruby"><span id="cb86-1"><a href="#cb86-1" aria-hidden="true"></a>f = <span class="dt">File</span>.new(<span class="st">"my-custom.log"</span>, <span class="st">"w+"</span>) <span class="co"># Log messages should go there</span></span>
<span id="cb86-2"><a href="#cb86-2" aria-hidden="true"></a><span class="dt">Datadog</span>.configure <span class="kw">do</span> |c|</span>
<span id="cb86-3"><a href="#cb86-3" aria-hidden="true"></a>  c.logger.instance = <span class="dt">Logger</span>.new(f) <span class="co"># Overriding the default logger</span></span>
<span id="cb86-4"><a href="#cb86-4" aria-hidden="true"></a>  c.logger.level = ::<span class="dt">Logger</span>::<span class="dt">INFO</span></span>
<span id="cb86-5"><a href="#cb86-5" aria-hidden="true"></a><span class="kw">end</span></span>
<span id="cb86-6"><a href="#cb86-6" aria-hidden="true"></a></span>
<span id="cb86-7"><a href="#cb86-7" aria-hidden="true"></a><span class="dt">Datadog</span>.logger.info { <span class="st">"this is typically called by tracing code"</span> }</span></code></pre></div>
<h4 id="environment-and-tags">Environment and tags</h4>
<p>By default, the trace Agent (not this library, but the program running in the background collecting data from various clients) uses the tags set in the Agent config file. You can configure the application to automatically tag your traces and metrics, using the following environment variables:</p>
<ul>
<li>
<code>DD_ENV</code>: Your application environment (e.g. <code>production</code>, <code>staging</code>, etc.)</li>
<li>
<code>DD_SERVICE</code>: Your application’s default service name (e.g. <code>billing-api</code>)</li>
<li>
<code>DD_VERSION</code>: Your application version (e.g. <code>2.5</code>, <code>202003181415</code>, <code>1.3-alpha</code>, etc.)</li>
<li>
<code>DD_TAGS</code>: Custom tags in value pairs separated by <code>,</code> (e.g. <code>layer:api,team:intake</code>)
<ul>
<li>If <code>DD_ENV</code>, <code>DD_SERVICE</code> or <code>DD_VERSION</code> are set, it will override any respective <code>env</code>/<code>service</code>/<code>version</code> tag defined in <code>DD_TAGS</code>.</li>
<li>If <code>DD_ENV</code>, <code>DD_SERVICE</code> or <code>DD_VERSION</code> are NOT set, tags defined in <code>DD_TAGS</code> will be used to populate <code>env</code>/<code>service</code>/<code>version</code> respectively.</li>
</ul>
</li>
</ul>
<p>These values can also be overridden at the tracer level:</p>
<div class="sourceCode" id="cb87"><pre class="sourceCode ruby"><code class="sourceCode ruby"><span id="cb87-1"><a href="#cb87-1" aria-hidden="true"></a><span class="dt">Datadog</span>.configure <span class="kw">do</span> |c|</span>
<span id="cb87-2"><a href="#cb87-2" aria-hidden="true"></a>  c.service = <span class="st">'billing-api'</span></span>
<span id="cb87-3"><a href="#cb87-3" aria-hidden="true"></a>  c.env = <span class="st">'test'</span></span>
<span id="cb87-4"><a href="#cb87-4" aria-hidden="true"></a>  c.tags = { <span class="st">'team'</span> =&gt; <span class="st">'qa'</span> }</span>
<span id="cb87-5"><a href="#cb87-5" aria-hidden="true"></a>  c.version = <span class="st">'1.3-alpha'</span></span>
<span id="cb87-6"><a href="#cb87-6" aria-hidden="true"></a><span class="kw">end</span></span></code></pre></div>
<p>This enables you to set this value on a per application basis, so you can have for example several applications reporting for different environments on the same host.</p>
<p>Tags can also be set directly on individual spans, which will supersede any conflicting tags defined at the application level.</p>
<h4 id="debugging-and-diagnostics">Debugging and diagnostics</h4>
<p>There are two different suggested means of producing diagnostics for tracing:</p>
<h5 id="enabling-debug-mode">Enabling debug mode</h5>
<p>Switching the library into debug mode will produce verbose, detailed logs about tracing activity, including any suppressed errors. This output can be helpful in identifying errors, or confirming trace output to the Agent.</p>
<p>You can enable this via <code>diagnostics.debug = true</code> or <code>DD_TRACE_DEBUG</code>.</p>
<div class="sourceCode" id="cb88"><pre class="sourceCode ruby"><code class="sourceCode ruby"><span id="cb88-1"><a href="#cb88-1" aria-hidden="true"></a><span class="dt">Datadog</span>.configure { |c| c.diagnostics.debug = <span class="dv">true</span> }</span></code></pre></div>
<p><strong>We do NOT recommend use of this feature in production or other sensitive environments</strong>, as it can be very verbose under load. It’s best to use this in a controlled environment where you can control application load.</p>
<h5 id="enabling-startup-logs">Enabling startup logs</h5>
<p>Startup logs produce a report of tracing state when the application is initially configured. This can be helpful for confirming that configuration and instrumentation is activated correctly.</p>
<p>You can enable this via <code>diagnostics.startup_logs.enabled = true</code> or <code>DD_TRACE_STARTUP_LOGS</code>.</p>
<div class="sourceCode" id="cb89"><pre class="sourceCode ruby"><code class="sourceCode ruby"><span id="cb89-1"><a href="#cb89-1" aria-hidden="true"></a><span class="dt">Datadog</span>.configure { |c| c.diagnostics.startup_logs.enabled = <span class="dv">true</span> }</span></code></pre></div>
<p>By default, this will be activated whenever <code>ddtrace</code> detects the application is running in a non-development environment.</p>
<h3 id="sampling">Sampling</h3>
<p>See <a href="https://docs.datadoghq.com/tracing/trace_pipeline/ingestion_mechanisms/?tab=ruby">Ingestion Mechanisms</a> for a list of all the sampling options available.</p>
<h4 id="priority-sampling">Priority sampling</h4>
<p>Priority sampling decides whether to keep a trace by using a priority attribute propagated for distributed traces. Its value indicates to the Agent and the backend about how important the trace is.</p>
<p>The sampler can set the priority to the following values:</p>
<ul>
<li>
<code>Datadog::Tracing::Sampling::Ext::Priority::AUTO_REJECT</code>: the sampler automatically decided to reject the trace.</li>
<li>
<code>Datadog::Tracing::Sampling::Ext::Priority::AUTO_KEEP</code>: the sampler automatically decided to keep the trace.</li>
</ul>
<p>Priority sampling is enabled by default. Enabling it ensures that your sampled distributed traces will be complete. Once enabled, the sampler will automatically assign a priority of 0 or 1 to traces, depending on their service and volume.</p>
<p>You can also set this priority manually to either drop a non-interesting trace or to keep an important one. For that, set the <code>TraceOperation#sampling_priority</code> to:</p>
<ul>
<li>
<code>Datadog::Tracing::Sampling::Ext::Priority::USER_REJECT</code>: the user asked to reject the trace.</li>
<li>
<code>Datadog::Tracing::Sampling::Ext::Priority::USER_KEEP</code>: the user asked to keep the trace.</li>
</ul>
<p>When not using <a href="#distributed-tracing">distributed tracing</a>, you may change the priority at any time, as long as the trace incomplete. But it has to be done before any context propagation (fork, RPC calls) to be useful in a distributed context. Changing the priority after the context has been propagated causes different parts of a distributed trace to use different priorities. Some parts might be kept, some parts might be rejected, and this can cause the trace to be partially stored and remain incomplete.</p>
<p>For this reason, if you change the priority, we recommend you do it as early as possible.</p>
<p>To change the sampling priority, you can use the following methods:</p>
<div class="sourceCode" id="cb90"><pre class="sourceCode ruby"><code class="sourceCode ruby"><span id="cb90-1"><a href="#cb90-1" aria-hidden="true"></a><span class="co"># Rejects the active trace</span></span>
<span id="cb90-2"><a href="#cb90-2" aria-hidden="true"></a><span class="dt">Datadog</span>::<span class="dt">Tracing</span>.reject!</span>
<span id="cb90-3"><a href="#cb90-3" aria-hidden="true"></a></span>
<span id="cb90-4"><a href="#cb90-4" aria-hidden="true"></a><span class="co"># Keeps the active trace</span></span>
<span id="cb90-5"><a href="#cb90-5" aria-hidden="true"></a><span class="dt">Datadog</span>::<span class="dt">Tracing</span>.keep!</span></code></pre></div>
<p>It’s safe to use <code>Datadog::Tracing.reject!</code> and <code>Datadog::Tracing.keep!</code> when no trace is active.</p>
<p>You can also reject a specific trace instance:</p>
<div class="sourceCode" id="cb91"><pre class="sourceCode ruby"><code class="sourceCode ruby"><span id="cb91-1"><a href="#cb91-1" aria-hidden="true"></a><span class="co"># First, grab the active trace</span></span>
<span id="cb91-2"><a href="#cb91-2" aria-hidden="true"></a>trace = <span class="dt">Datadog</span>::<span class="dt">Tracing</span>.active_trace</span>
<span id="cb91-3"><a href="#cb91-3" aria-hidden="true"></a></span>
<span id="cb91-4"><a href="#cb91-4" aria-hidden="true"></a><span class="co"># Rejects the trace</span></span>
<span id="cb91-5"><a href="#cb91-5" aria-hidden="true"></a>trace.reject!</span>
<span id="cb91-6"><a href="#cb91-6" aria-hidden="true"></a></span>
<span id="cb91-7"><a href="#cb91-7" aria-hidden="true"></a><span class="co"># Keeps the trace</span></span>
<span id="cb91-8"><a href="#cb91-8" aria-hidden="true"></a>trace.keep!</span></code></pre></div>
<h4 id="single-span-sampling">Single Span Sampling</h4>
<p>You can configure sampling rule that allow you keep spans despite their respective traces being dropped by a trace-level sampling rule.</p>
<p>This allows you to keep important spans when trace-level sampling is applied. Is is not possible to drop spans using Single Span Sampling.</p>
<p>To configure it, see the <a href="https://docs.datadoghq.com/tracing/trace_pipeline/ingestion_mechanisms/?tab=ruby#single-spans">Ingestion Mechanisms documentation</a>.</p>
<h4 id="application-side-sampling">Application-side sampling</h4>
<p>While the Datadog Agent can sample traces to reduce bandwidth usage, application-side sampling reduces the performance overhead in the host application.</p>
<p><strong>Application-side sampling drops traces as early as possible. This causes the <a href="https://docs.datadoghq.com/tracing/trace_pipeline/ingestion_controls/">Ingestion Controls</a> page to not receive enough information to report accurate sampling rates. Use only when reducing the tracing overhead is paramount.</strong></p>
<p>If you are use this feature, please let us know by <a href="https://github.com/DataDog/dd-trace-rb/issues/new">opening an issue on GitHub</a>, so we can better understand and support your use case.</p>
<p>You can configure <em>Application-side sampling</em> with the following settings:</p>
<div class="sourceCode" id="cb92"><pre class="sourceCode ruby"><code class="sourceCode ruby"><span id="cb92-1"><a href="#cb92-1" aria-hidden="true"></a><span class="co"># Application-side sampling enabled: Ingestion Controls page will be inaccurate.</span></span>
<span id="cb92-2"><a href="#cb92-2" aria-hidden="true"></a>sampler = <span class="dt">Datadog</span>::<span class="dt">Tracing</span>::<span class="dt">Sampling</span>::<span class="dt">RateSampler</span>.new(<span class="fl">0.5</span>) <span class="co"># sample 50% of the traces</span></span>
<span id="cb92-3"><a href="#cb92-3" aria-hidden="true"></a></span>
<span id="cb92-4"><a href="#cb92-4" aria-hidden="true"></a><span class="dt">Datadog</span>.configure <span class="kw">do</span> |c|</span>
<span id="cb92-5"><a href="#cb92-5" aria-hidden="true"></a>  c.tracing.sampler = sampler</span>
<span id="cb92-6"><a href="#cb92-6" aria-hidden="true"></a><span class="kw">end</span></span></code></pre></div>
<p>See <a href="#additional-configuration">Additional Configuration</a> for more details about these settings.</p>
<h3 id="distributed-tracing">Distributed Tracing</h3>
<p>Distributed tracing allows traces to be propagated across multiple instrumented applications so that a request can be presented as a single trace, rather than a separate trace per service.</p>
<p>To trace requests across application boundaries, the following must be propagated between each application:</p>
<table>
<colgroup>
<col style="width: 13%">
<col style="width: 4%">
<col style="width: 81%">
</colgroup>
<thead>
<tr class="header">
<th>Property</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr class="odd">
<td><strong>Trace ID</strong></td>
<td>Integer</td>
<td>ID of the trace. This value should be the same across all requests that belong to the same trace.</td>
</tr>
<tr class="even">
<td><strong>Parent Span ID</strong></td>
<td>Integer</td>
<td>ID of the span in the service originating the request. This value will always be different for each request within a trace.</td>
</tr>
<tr class="odd">
<td><strong>Sampling Priority</strong></td>
<td>Integer</td>
<td>Sampling priority level for the trace. This value should be the same across all requests that belong to the same trace.</td>
</tr>
</tbody>
</table>
<p>Such propagation can be visualized as:</p>
<pre><code>Service A:
  Trace ID:  100000000000000001
  Parent ID: 0
  Span ID:   100000000000000123
  Priority:  1

  |
  | Service B Request:
  |   Metadata:
  |     Trace ID:  100000000000000001
  |     Parent ID: 100000000000000123
  |     Priority:  1
  |
  V

Service B:
  Trace ID:  100000000000000001
  Parent ID: 100000000000000123
  Span ID:   100000000000000456
  Priority:  1

  |
  | Service C Request:
  |   Metadata:
  |     Trace ID:  100000000000000001
  |     Parent ID: 100000000000000456
  |     Priority:  1
  |
  V

Service C:
  Trace ID:  100000000000000001
  Parent ID: 100000000000000456
  Span ID:   100000000000000789
  Priority:  1</code></pre>
<p><strong>Via HTTP</strong></p>
<p>For HTTP requests between instrumented applications, this trace metadata is propagated by use of HTTP Request headers:</p>
<table>
<thead>
<tr class="header">
<th>Property</th>
<th>Type</th>
<th>HTTP Header name</th>
</tr>
</thead>
<tbody>
<tr class="odd">
<td><strong>Trace ID</strong></td>
<td>Integer</td>
<td><code>x-datadog-trace-id</code></td>
</tr>
<tr class="even">
<td><strong>Parent Span ID</strong></td>
<td>Integer</td>
<td><code>x-datadog-parent-id</code></td>
</tr>
<tr class="odd">
<td><strong>Sampling Priority</strong></td>
<td>Integer</td>
<td><code>x-datadog-sampling-priority</code></td>
</tr>
</tbody>
</table>
<p>Such that:</p>
<pre><code>Service A:
  Trace ID:  100000000000000001
  Parent ID: 0
  Span ID:   100000000000000123
  Priority:  1

  |
  | Service B HTTP Request:
  |   Headers:
  |     x-datadog-trace-id:          100000000000000001
  |     x-datadog-parent-id:         100000000000000123
  |     x-datadog-sampling-priority: 1
  |
  V

Service B:
  Trace ID:  100000000000000001
  Parent ID: 100000000000000123
  Span ID:   100000000000000456
  Priority:  1

  |
  | Service C HTTP Request:
  |   Headers:
  |     x-datadog-trace-id:          100000000000000001
  |     x-datadog-parent-id:         100000000000000456
  |     x-datadog-sampling-priority: 1
  |
  V

Service C:
  Trace ID:  100000000000000001
  Parent ID: 100000000000000456
  Span ID:   100000000000000789
  Priority:  1</code></pre>
<h4 id="distributed-header-formats">Distributed header formats</h4>
<p>Tracing supports the following distributed trace formats:</p>
<ul>
<li><code>Datadog</code></li>
<li>
<code>tracecontext</code>: <a href="https://www.w3.org/TR/trace-context/">W3C Trace Context</a>
</li>
<li>
<code>b3multi</code>: <a href="https://github.com/openzipkin/b3-propagation#multiple-headers">B3 multiple-headers</a>
</li>
<li>
<code>b3</code>: <a href="https://github.com/openzipkin/b3-propagation#single-header">B3 single-header</a>
</li>
<li>
<code>none</code>: No-op.</li>
</ul>
<p>You can enable/disable the use of these formats via <code>Datadog.configure</code>:</p>
<div class="sourceCode" id="cb95"><pre class="sourceCode ruby"><code class="sourceCode ruby"><span id="cb95-1"><a href="#cb95-1" aria-hidden="true"></a><span class="dt">Datadog</span>.configure <span class="kw">do</span> |c|</span>
<span id="cb95-2"><a href="#cb95-2" aria-hidden="true"></a>  <span class="co"># List of header formats that should be extracted</span></span>
<span id="cb95-3"><a href="#cb95-3" aria-hidden="true"></a>  c.tracing.distributed_tracing.propagation_extract_style = [ <span class="st">'tracecontext'</span>, <span class="st">'Datadog'</span>, <span class="st">'b3'</span> ]</span>
<span id="cb95-4"><a href="#cb95-4" aria-hidden="true"></a></span>
<span id="cb95-5"><a href="#cb95-5" aria-hidden="true"></a>  <span class="co"># List of header formats that should be injected</span></span>
<span id="cb95-6"><a href="#cb95-6" aria-hidden="true"></a>  c.tracing.distributed_tracing.propagation_inject_style = [ <span class="st">'tracecontext'</span>, <span class="st">'Datadog'</span> ]</span>
<span id="cb95-7"><a href="#cb95-7" aria-hidden="true"></a><span class="kw">end</span></span></code></pre></div>
<p><strong>Activating distributed tracing for integrations</strong></p>
<p>Many integrations included in <code>ddtrace</code> support distributed tracing. Distributed tracing is enabled by default in Agent v7 and most versions of Agent v6. If needed, you can activate distributed tracing with configuration settings.</p>
<ul>
<li>If your application receives requests from services with distributed tracing activated, you must activate distributed tracing on the integrations that handle these requests (e.g. Rails)</li>
<li>If your application send requests to services with distributed tracing activated, you must activate distributed tracing on the integrations that send these requests (e.g. Faraday)</li>
<li>If your application both sends and receives requests implementing distributed tracing, it must activate all integrations that handle these requests.</li>
</ul>
<p>For more details on how to activate distributed tracing for integrations, see their documentation:</p>
<ul>
<li><a href="#excon">Excon</a></li>
<li><a href="#faraday">Faraday</a></li>
<li><a href="#rest-client">Rest Client</a></li>
<li><a href="#nethttp">Net/HTTP</a></li>
<li><a href="#rack">Rack</a></li>
<li><a href="#rails">Rails</a></li>
<li><a href="#sinatra">Sinatra</a></li>
<li><a href="#httprb">http.rb</a></li>
<li><a href="#httpclient">httpclient</a></li>
<li><a href="#httpx">httpx</a></li>
</ul>
<p><strong>Using the HTTP propagator</strong></p>
<p>To make the process of propagating this metadata easier, you can use the <code>Datadog::Tracing::Propagation::HTTP</code> module.</p>
<p>On the client:</p>
<div class="sourceCode" id="cb96"><pre class="sourceCode ruby"><code class="sourceCode ruby"><span id="cb96-1"><a href="#cb96-1" aria-hidden="true"></a><span class="dt">Datadog</span>::<span class="dt">Tracing</span>.trace(<span class="st">'web.call'</span>) <span class="kw">do</span> |span, trace|</span>
<span id="cb96-2"><a href="#cb96-2" aria-hidden="true"></a>  <span class="co"># Inject trace headers into request headers (`env` must be a Hash)</span></span>
<span id="cb96-3"><a href="#cb96-3" aria-hidden="true"></a>  <span class="dt">Datadog</span>::<span class="dt">Tracing</span>::<span class="dt">Propagation</span>::<span class="dt">HTTP</span>.inject!(trace.to_digest, env)</span>
<span id="cb96-4"><a href="#cb96-4" aria-hidden="true"></a><span class="kw">end</span></span></code></pre></div>
<p>On the server:</p>
<div class="sourceCode" id="cb97"><pre class="sourceCode ruby"><code class="sourceCode ruby"><span id="cb97-1"><a href="#cb97-1" aria-hidden="true"></a>trace_digest = <span class="dt">Datadog</span>::<span class="dt">Tracing</span>::<span class="dt">Propagation</span>::<span class="dt">HTTP</span>.extract(request.env)</span>
<span id="cb97-2"><a href="#cb97-2" aria-hidden="true"></a></span>
<span id="cb97-3"><a href="#cb97-3" aria-hidden="true"></a><span class="dt">Datadog</span>::<span class="dt">Tracing</span>.trace(<span class="st">'web.work'</span>, <span class="st">continue_from: </span>trace_digest) <span class="kw">do</span> |span|</span>
<span id="cb97-4"><a href="#cb97-4" aria-hidden="true"></a>  <span class="co"># Do web work...</span></span>
<span id="cb97-5"><a href="#cb97-5" aria-hidden="true"></a><span class="kw">end</span></span></code></pre></div>
<h3 id="http-request-queuing">HTTP request queuing</h3>
<p>Traces that originate from HTTP requests can be configured to include the time spent in a frontend web server or load balancer queue before the request reaches the Ruby application.</p>
<p>This feature is disabled by default. To activate it, you must add an <code>X-Request-Start</code> or <code>X-Queue-Start</code> header from your web server (i.e., Nginx). The following is an Nginx configuration example:</p>
<pre><code># /etc/nginx/conf.d/ruby_service.conf
server {
    listen 8080;

    location / {
      proxy_set_header X-Request-Start "t=${msec}";
      proxy_pass http://web:3000;
    }
}</code></pre>
<p>Then you must enable the request queuing feature. The following options are available for the <code>:request_queuing</code> configuration:</p>
<table>
<colgroup>
<col style="width: 62%">
<col style="width: 37%">
</colgroup>
<thead>
<tr class="header">
<th>Option</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr class="odd">
<td><code>:include_request</code></td>
<td>A <code>http_server.queue</code> span will be the root span of a trace, including the total time spent processing the request <em>in addition</em> to the time spent waiting for the request to begin being processed. This is the behavior when the configuration is set to <code>true</code>. This is the selected configuration when set to <code>true</code>.</td>
</tr>
<tr class="even">
<td><code>:exclude_request</code></td>
<td>A <code>http.proxy.request</code> span will be the root span of a trace, with the <code>http.proxy.queue</code> child span duration representing only the time spent waiting for the request to begin being processed. <em>This is an experimental feature!</em>
</td>
</tr>
</tbody>
</table>
<p>For Rack-based applications, see the <a href="#rack">documentation</a> for details.</p>
<h3 id="processing-pipeline">Processing Pipeline</h3>
<p>Some applications might require that traces be altered or filtered out before they are sent to Datadog. The processing pipeline allows you to create <em>processors</em> to define such behavior.</p>
<h4 id="filtering">Filtering</h4>
<p>You can use the <code>Datadog::Tracing::Pipeline::SpanFilter</code> processor to remove spans, when the block evaluates as truthy:</p>
<div class="sourceCode" id="cb99"><pre class="sourceCode ruby"><code class="sourceCode ruby"><span id="cb99-1"><a href="#cb99-1" aria-hidden="true"></a><span class="dt">Datadog</span>::<span class="dt">Tracing</span>.before_flush(</span>
<span id="cb99-2"><a href="#cb99-2" aria-hidden="true"></a>  <span class="co"># Remove spans that match a particular resource</span></span>
<span id="cb99-3"><a href="#cb99-3" aria-hidden="true"></a>  <span class="dt">Datadog</span>::<span class="dt">Tracing</span>::<span class="dt">Pipeline</span>::<span class="dt">SpanFilter</span>.new { |span| span.resource =~ <span class="ot">/PingController/</span> },</span>
<span id="cb99-4"><a href="#cb99-4" aria-hidden="true"></a>  <span class="co"># Remove spans that are trafficked to localhost</span></span>
<span id="cb99-5"><a href="#cb99-5" aria-hidden="true"></a>  <span class="dt">Datadog</span>::<span class="dt">Tracing</span>::<span class="dt">Pipeline</span>::<span class="dt">SpanFilter</span>.new { |span| span.get_tag(<span class="st">'host'</span>) == <span class="st">'localhost'</span> }</span>
<span id="cb99-6"><a href="#cb99-6" aria-hidden="true"></a>)</span></code></pre></div>
<h4 id="processing">Processing</h4>
<p>You can use the <code>Datadog::Tracing::Pipeline::SpanProcessor</code> processor to modify spans:</p>
<div class="sourceCode" id="cb100"><pre class="sourceCode ruby"><code class="sourceCode ruby"><span id="cb100-1"><a href="#cb100-1" aria-hidden="true"></a><span class="dt">Datadog</span>::<span class="dt">Tracing</span>.before_flush(</span>
<span id="cb100-2"><a href="#cb100-2" aria-hidden="true"></a>  <span class="co"># Strip matching text from the resource field</span></span>
<span id="cb100-3"><a href="#cb100-3" aria-hidden="true"></a>  <span class="dt">Datadog</span>::<span class="dt">Tracing</span>::<span class="dt">Pipeline</span>::<span class="dt">SpanProcessor</span>.new { |span| span.resource.gsub!(<span class="ot">/password=.*/</span>, <span class="st">''</span>) }</span>
<span id="cb100-4"><a href="#cb100-4" aria-hidden="true"></a>)</span></code></pre></div>
<h4 id="custom-processor">Custom processor</h4>
<p>Processors can be any object that responds to <code>#call</code> accepting <code>trace</code> as an argument (which is an <code>Array</code> of <code>Datadog::Span</code>s.)</p>
<p>For example, using the short-hand block syntax:</p>
<div class="sourceCode" id="cb101"><pre class="sourceCode ruby"><code class="sourceCode ruby"><span id="cb101-1"><a href="#cb101-1" aria-hidden="true"></a><span class="dt">Datadog</span>::<span class="dt">Tracing</span>.before_flush <span class="kw">do</span> |trace|</span>
<span id="cb101-2"><a href="#cb101-2" aria-hidden="true"></a>   <span class="co"># Processing logic...</span></span>
<span id="cb101-3"><a href="#cb101-3" aria-hidden="true"></a>   trace</span>
<span id="cb101-4"><a href="#cb101-4" aria-hidden="true"></a><span class="kw">end</span></span></code></pre></div>
<p>For a custom processor class:</p>
<div class="sourceCode" id="cb102"><pre class="sourceCode ruby"><code class="sourceCode ruby"><span id="cb102-1"><a href="#cb102-1" aria-hidden="true"></a><span class="kw">class</span> <span class="dt">MyCustomProcessor</span></span>
<span id="cb102-2"><a href="#cb102-2" aria-hidden="true"></a>  <span class="kw">def</span> call(trace)</span>
<span id="cb102-3"><a href="#cb102-3" aria-hidden="true"></a>    <span class="co"># Processing logic...</span></span>
<span id="cb102-4"><a href="#cb102-4" aria-hidden="true"></a>    trace</span>
<span id="cb102-5"><a href="#cb102-5" aria-hidden="true"></a>  <span class="kw">end</span></span>
<span id="cb102-6"><a href="#cb102-6" aria-hidden="true"></a><span class="kw">end</span></span>
<span id="cb102-7"><a href="#cb102-7" aria-hidden="true"></a></span>
<span id="cb102-8"><a href="#cb102-8" aria-hidden="true"></a><span class="dt">Datadog</span>::<span class="dt">Tracing</span>.before_flush(<span class="dt">MyCustomProcessor</span>.new)</span></code></pre></div>
<p>In both cases, the processor method <em>must</em> return the <code>trace</code> object; this return value will be passed to the next processor in the pipeline.</p>
<h4 id="caveats">Caveats</h4>
<ol type="1">
<li>Removed spans will not generate trace metrics, affecting monitors and dashboards.</li>
<li>Removing a span also removes all children spans from the removed span. This prevents orphan spans in the trace graph.</li>
<li>The <a href="#enabling-debug-mode">debug mode logs</a> reports the state of spans <em>before</em> the Processing Pipeline is executed: modified or removed spans will display their original state in debug mode logs.</li>
</ol>
<h3 id="trace-correlation">Trace correlation</h3>
<p>In many cases, such as logging, it may be useful to correlate trace IDs to other events or data streams, for easier cross-referencing.</p>
<h4 id="for-logging-in-rails-applications">For logging in Rails applications</h4>
<h5 id="automatic">Automatic</h5>
<p>For Rails applications using the default logger (<code>ActiveSupport::TaggedLogging</code>), <code>lograge</code> or <code>semantic_logger</code>, trace correlation injection is enabled by default.</p>
<p>It can be disabled by setting the environment variable <code>DD_LOGS_INJECTION=false</code>.</p>
<h4 id="for-logging-in-ruby-applications">For logging in Ruby applications</h4>
<p>To add correlation IDs to your logger, add a log formatter which retrieves the correlation IDs with <code>Datadog::Tracing.correlation</code>, then add them to the message.</p>
<p>To properly correlate with Datadog logging, be sure the following is present in the log message, in order as they appear:</p>
<ul>
<li>
<code>dd.env=&lt;ENV&gt;</code>: Where <code>&lt;ENV&gt;</code> is equal to <code>Datadog::Tracing.correlation.env</code>. Omit if no environment is configured.</li>
<li>
<code>dd.service=&lt;SERVICE&gt;</code>: Where <code>&lt;SERVICE&gt;</code> is equal to <code>Datadog::Tracing.correlation.service</code>. Omit if no default service name is configured.</li>
<li>
<code>dd.version=&lt;VERSION&gt;</code>: Where <code>&lt;VERSION&gt;</code> is equal to <code>Datadog::Tracing.correlation.version</code>. Omit if no application version is configured.</li>
<li>
<code>dd.trace_id=&lt;TRACE_ID&gt;</code>: Where <code>&lt;TRACE_ID&gt;</code> is equal to <code>Datadog::Tracing.correlation.trace_id</code> or <code>0</code> if no trace is active during logging.</li>
<li>
<code>dd.span_id=&lt;SPAN_ID&gt;</code>: Where <code>&lt;SPAN_ID&gt;</code> is equal to <code>Datadog::Tracing.correlation.span_id</code> or <code>0</code> if no trace is active during logging.</li>
</ul>
<p><code>Datadog::Tracing.log_correlation</code> will return <code>dd.env=&lt;ENV&gt; dd.service=&lt;SERVICE&gt; dd.version=&lt;VERSION&gt; dd.trace_id=&lt;TRACE_ID&gt; dd.span_id=&lt;SPAN_ID&gt;</code>.</p>
<p>If a trace is not active and the application environment &amp; version is not configured, it will return <code>dd.env= dd.service= dd.version= dd.trace_id=0 dd.span_id=0</code>.</p>
<p>An example of this in practice:</p>
<div class="sourceCode" id="cb103"><pre class="sourceCode ruby"><code class="sourceCode ruby"><span id="cb103-1"><a href="#cb103-1" aria-hidden="true"></a>require <span class="st">'ddtrace'</span></span>
<span id="cb103-2"><a href="#cb103-2" aria-hidden="true"></a>require <span class="st">'logger'</span></span>
<span id="cb103-3"><a href="#cb103-3" aria-hidden="true"></a></span>
<span id="cb103-4"><a href="#cb103-4" aria-hidden="true"></a><span class="dt">ENV</span>[<span class="st">'DD_ENV'</span>] = <span class="st">'production'</span></span>
<span id="cb103-5"><a href="#cb103-5" aria-hidden="true"></a><span class="dt">ENV</span>[<span class="st">'DD_SERVICE'</span>] = <span class="st">'billing-api'</span></span>
<span id="cb103-6"><a href="#cb103-6" aria-hidden="true"></a><span class="dt">ENV</span>[<span class="st">'DD_VERSION'</span>] = <span class="st">'2.5.17'</span></span>
<span id="cb103-7"><a href="#cb103-7" aria-hidden="true"></a></span>
<span id="cb103-8"><a href="#cb103-8" aria-hidden="true"></a>logger = <span class="dt">Logger</span>.new(<span class="dt">STDOUT</span>)</span>
<span id="cb103-9"><a href="#cb103-9" aria-hidden="true"></a>logger.progname = <span class="st">'my_app'</span></span>
<span id="cb103-10"><a href="#cb103-10" aria-hidden="true"></a>logger.formatter  = proc <span class="kw">do</span> |severity, datetime, progname, msg|</span>
<span id="cb103-11"><a href="#cb103-11" aria-hidden="true"></a>  <span class="st">"[</span><span class="ot">#{</span>datetime<span class="ot">}</span><span class="st">][</span><span class="ot">#{</span>progname<span class="ot">}</span><span class="st">][</span><span class="ot">#{</span>severity<span class="ot">}</span><span class="st">][</span><span class="ot">#{</span><span class="dt">Datadog</span>::<span class="dt">Tracing</span>.log_correlation<span class="ot">}</span><span class="st">] </span><span class="ot">#{</span>msg<span class="ot">}</span><span class="st">\n"</span></span>
<span id="cb103-12"><a href="#cb103-12" aria-hidden="true"></a><span class="kw">end</span></span>
<span id="cb103-13"><a href="#cb103-13" aria-hidden="true"></a></span>
<span id="cb103-14"><a href="#cb103-14" aria-hidden="true"></a><span class="co"># When no trace is active</span></span>
<span id="cb103-15"><a href="#cb103-15" aria-hidden="true"></a>logger.warn(<span class="st">'This is an untraced operation.'</span>)</span>
<span id="cb103-16"><a href="#cb103-16" aria-hidden="true"></a><span class="co"># [2019-01-16 18:38:41 +0000][my_app][WARN][dd.env=production dd.service=billing-api dd.version=2.5.17 dd.trace_id=0 dd.span_id=0] This is an untraced operation.</span></span>
<span id="cb103-17"><a href="#cb103-17" aria-hidden="true"></a></span>
<span id="cb103-18"><a href="#cb103-18" aria-hidden="true"></a><span class="co"># When a trace is active</span></span>
<span id="cb103-19"><a href="#cb103-19" aria-hidden="true"></a><span class="dt">Datadog</span>::<span class="dt">Tracing</span>.trace(<span class="st">'my.operation'</span>) { logger.warn(<span class="st">'This is a traced operation.'</span>) }</span>
<span id="cb103-20"><a href="#cb103-20" aria-hidden="true"></a><span class="co"># [2019-01-16 18:38:41 +0000][my_app][WARN][dd.env=production dd.service=billing-api dd.version=2.5.17 dd.trace_id=8545847825299552251 dd.span_id=3711755234730770098] This is a traced operation.</span></span></code></pre></div>
<h3 id="configuring-the-transport-layer">Configuring the transport layer</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>Through any explicitly provided configuration settings (hostname/port/transport)</li>
<li>Through Unix Domain Socket (UDS) located at <code>/var/run/datadog/apm.socket</code>
</li>
<li>Through HTTP over TCP to <code>127.0.0.1:8126</code>
</li>
</ol>
<p>However, the tracer can be configured to send its trace data to alternative destinations, or by alternative protocols.</p>
<h4 id="changing-default-agent-hostname-and-port">Changing default Agent hostname and port</h4>
<p>To change the Agent host or port, provide <code>DD_AGENT_HOST</code> and <code>DD_TRACE_AGENT_PORT</code>.</p>
<p>OR within a <code>Datadog.configure</code> block, provide the following settings:</p>
<div class="sourceCode" id="cb104"><pre class="sourceCode ruby"><code class="sourceCode ruby"><span id="cb104-1"><a href="#cb104-1" aria-hidden="true"></a><span class="dt">Datadog</span>.configure <span class="kw">do</span> |c|</span>
<span id="cb104-2"><a href="#cb104-2" aria-hidden="true"></a>  c.agent.host = <span class="st">'127.0.0.1'</span></span>
<span id="cb104-3"><a href="#cb104-3" aria-hidden="true"></a>  c.agent.port = <span class="dv">8126</span></span>
<span id="cb104-4"><a href="#cb104-4" aria-hidden="true"></a><span class="kw">end</span></span></code></pre></div>
<p>See <a href="#additional-configuration">Additional Configuration</a> for more details.</p>
<h4 id="using-the-nethttp-adapter">Using the Net::HTTP adapter</h4>
<p>The <code>Net</code> adapter submits traces using <code>Net::HTTP</code> over TCP. It is the default transport adapter.</p>
<div class="sourceCode" id="cb105"><pre class="sourceCode ruby"><code class="sourceCode ruby"><span id="cb105-1"><a href="#cb105-1" aria-hidden="true"></a><span class="dt">Datadog</span>.configure <span class="kw">do</span> |c|</span>
<span id="cb105-2"><a href="#cb105-2" aria-hidden="true"></a>  c.tracing.transport_options = proc { |t|</span>
<span id="cb105-3"><a href="#cb105-3" aria-hidden="true"></a>    <span class="co"># Hostname, port, and additional options. :timeout is in seconds.</span></span>
<span id="cb105-4"><a href="#cb105-4" aria-hidden="true"></a>    t.adapter <span class="st">:net_http</span>, <span class="st">'127.0.0.1'</span>, <span class="dv">8126</span>, <span class="st">timeout: </span><span class="dv">30</span></span>
<span id="cb105-5"><a href="#cb105-5" aria-hidden="true"></a>  }</span>
<span id="cb105-6"><a href="#cb105-6" aria-hidden="true"></a><span class="kw">end</span></span></code></pre></div>
<h4 id="using-the-unix-domain-socket-uds-adapter">Using the Unix Domain Socket (UDS) adapter</h4>
<p>The <code>UnixSocket</code> adapter submits traces using <code>Net::HTTP</code> over Unix socket.</p>
<p>To use, first configure your trace Agent to listen by Unix socket, then configure the tracer with:</p>
<div class="sourceCode" id="cb106"><pre class="sourceCode ruby"><code class="sourceCode ruby"><span id="cb106-1"><a href="#cb106-1" aria-hidden="true"></a><span class="dt">Datadog</span>.configure <span class="kw">do</span> |c|</span>
<span id="cb106-2"><a href="#cb106-2" aria-hidden="true"></a>  c.tracing.transport_options = proc { |t|</span>
<span id="cb106-3"><a href="#cb106-3" aria-hidden="true"></a>    <span class="co"># Provide local path to trace Agent Unix socket</span></span>
<span id="cb106-4"><a href="#cb106-4" aria-hidden="true"></a>    t.adapter <span class="st">:unix</span>, <span class="st">'/tmp/ddagent/trace.sock'</span></span>
<span id="cb106-5"><a href="#cb106-5" aria-hidden="true"></a>  }</span>
<span id="cb106-6"><a href="#cb106-6" aria-hidden="true"></a><span class="kw">end</span></span></code></pre></div>
<h4 id="using-the-transport-test-adapter">Using the transport test adapter</h4>
<p>The <code>Test</code> adapter is a no-op transport that can optionally buffer requests. For use in test suites or other non-production environments.</p>
<div class="sourceCode" id="cb107"><pre class="sourceCode ruby"><code class="sourceCode ruby"><span id="cb107-1"><a href="#cb107-1" aria-hidden="true"></a><span class="dt">Datadog</span>.configure <span class="kw">do</span> |c|</span>
<span id="cb107-2"><a href="#cb107-2" aria-hidden="true"></a>  c.tracing.transport_options = proc { |t|</span>
<span id="cb107-3"><a href="#cb107-3" aria-hidden="true"></a>    <span class="co"># Set transport to no-op mode. Does not retain traces.</span></span>
<span id="cb107-4"><a href="#cb107-4" aria-hidden="true"></a>    t.adapter <span class="st">:test</span></span>
<span id="cb107-5"><a href="#cb107-5" aria-hidden="true"></a></span>
<span id="cb107-6"><a href="#cb107-6" aria-hidden="true"></a>    <span class="co"># Alternatively, you can provide a buffer to examine trace output.</span></span>
<span id="cb107-7"><a href="#cb107-7" aria-hidden="true"></a>    <span class="co"># The buffer must respond to '&lt;&lt;'.</span></span>
<span id="cb107-8"><a href="#cb107-8" aria-hidden="true"></a>    t.adapter <span class="st">:test</span>, []</span>
<span id="cb107-9"><a href="#cb107-9" aria-hidden="true"></a>  }</span>
<span id="cb107-10"><a href="#cb107-10" aria-hidden="true"></a><span class="kw">end</span></span></code></pre></div>
<h4 id="using-a-custom-transport-adapter">Using a custom transport adapter</h4>
<p>Custom adapters can be configured with:</p>
<div class="sourceCode" id="cb108"><pre class="sourceCode ruby"><code class="sourceCode ruby"><span id="cb108-1"><a href="#cb108-1" aria-hidden="true"></a><span class="dt">Datadog</span>.configure <span class="kw">do</span> |c|</span>
<span id="cb108-2"><a href="#cb108-2" aria-hidden="true"></a>  c.tracing.transport_options = proc { |t|</span>
<span id="cb108-3"><a href="#cb108-3" aria-hidden="true"></a>    <span class="co"># Initialize and pass an instance of the adapter</span></span>
<span id="cb108-4"><a href="#cb108-4" aria-hidden="true"></a>    custom_adapter = <span class="dt">CustomAdapter</span>.new</span>
<span id="cb108-5"><a href="#cb108-5" aria-hidden="true"></a>    t.adapter custom_adapter</span>
<span id="cb108-6"><a href="#cb108-6" aria-hidden="true"></a>  }</span>
<span id="cb108-7"><a href="#cb108-7" aria-hidden="true"></a><span class="kw">end</span></span></code></pre></div>
<h3 id="setting-the-time-provider">Setting the time provider</h3>
<p>By default, tracing uses a monotonic clock to measure the duration of spans, and timestamps (<code>-&gt;{ Time.now }</code>) for the start and end time.</p>
<p>When testing, it might be helpful to use a different time provider.</p>
<p>To change the function that provides timestamps, configure the following:</p>
<div class="sourceCode" id="cb109"><pre class="sourceCode ruby"><code class="sourceCode ruby"><span id="cb109-1"><a href="#cb109-1" aria-hidden="true"></a><span class="dt">Datadog</span>.configure <span class="kw">do</span> |c|</span>
<span id="cb109-2"><a href="#cb109-2" aria-hidden="true"></a>  <span class="co"># For Timecop, for example, `-&gt;{ Time.now_without_mock_time }` allows the tracer to use the real wall time.</span></span>
<span id="cb109-3"><a href="#cb109-3" aria-hidden="true"></a>  c.time_now_provider = -&gt; { <span class="dt">Time</span>.now_without_mock_time }</span>
<span id="cb109-4"><a href="#cb109-4" aria-hidden="true"></a><span class="kw">end</span></span></code></pre></div>
<p>Span duration calculation will still use the system monotonic clock when available, thus not being affected by this setting.</p>
<h3 id="metrics">Metrics</h3>
<p>The tracer and its integrations can produce some additional metrics that can provide useful insight into the performance of your application. These metrics are collected with <code>dogstatsd-ruby</code>, and can be sent to the same Datadog agent to which you send your traces.</p>
<p>To configure your application for metrics collection:</p>
<ol type="1">
<li><a href="https://docs.datadoghq.com/developers/dogstatsd/#setup">Configure your Datadog Agent for StatsD</a></li>
<li>Add <code>gem 'dogstatsd-ruby', '~&gt; 5.3'</code> to your Gemfile</li>
</ol>
<h4 id="for-application-runtime">For application runtime</h4>
<p>If runtime metrics are configured, the trace library will automatically collect and send metrics about the health of your application.</p>
<p>To configure runtime metrics, add the following configuration:</p>
<div class="sourceCode" id="cb110"><pre class="sourceCode ruby"><code class="sourceCode ruby"><span id="cb110-1"><a href="#cb110-1" aria-hidden="true"></a><span class="co"># config/initializers/datadog.rb</span></span>
<span id="cb110-2"><a href="#cb110-2" aria-hidden="true"></a>require <span class="st">'datadog/statsd'</span></span>
<span id="cb110-3"><a href="#cb110-3" aria-hidden="true"></a>require <span class="st">'ddtrace'</span></span>
<span id="cb110-4"><a href="#cb110-4" aria-hidden="true"></a></span>
<span id="cb110-5"><a href="#cb110-5" aria-hidden="true"></a><span class="dt">Datadog</span>.configure <span class="kw">do</span> |c|</span>
<span id="cb110-6"><a href="#cb110-6" aria-hidden="true"></a>  <span class="co"># To enable runtime metrics collection, set `true`. Defaults to `false`</span></span>
<span id="cb110-7"><a href="#cb110-7" aria-hidden="true"></a>  <span class="co"># You can also set DD_RUNTIME_METRICS_ENABLED=true to configure this.</span></span>
<span id="cb110-8"><a href="#cb110-8" aria-hidden="true"></a>  c.runtime_metrics.enabled = <span class="dv">true</span></span>
<span id="cb110-9"><a href="#cb110-9" aria-hidden="true"></a></span>
<span id="cb110-10"><a href="#cb110-10" aria-hidden="true"></a>  <span class="co"># Optionally, you can configure the Statsd instance used for sending runtime metrics.</span></span>
<span id="cb110-11"><a href="#cb110-11" aria-hidden="true"></a>  <span class="co"># Statsd is automatically configured with default settings if `dogstatsd-ruby` is available.</span></span>
<span id="cb110-12"><a href="#cb110-12" aria-hidden="true"></a>  <span class="co"># You can configure with host and port of Datadog Agent; defaults to 'localhost:8125'.</span></span>
<span id="cb110-13"><a href="#cb110-13" aria-hidden="true"></a>  c.runtime_metrics.statsd = <span class="dt">Datadog</span>::<span class="dt">Statsd</span>.new</span>
<span id="cb110-14"><a href="#cb110-14" aria-hidden="true"></a><span class="kw">end</span></span></code></pre></div>
<p>See the <a href="https://www.rubydoc.info/github/DataDog/dogstatsd-ruby/master/frames">Dogstatsd documentation</a> for more details about configuring <code>Datadog::Statsd</code>.</p>
<p>The stats are VM specific and will include:</p>
<table style="width:100%;">
<colgroup>
<col style="width: 23%">
<col style="width: 6%">
<col style="width: 54%">
<col style="width: 16%">
</colgroup>
<thead>
<tr class="header">
<th>Name</th>
<th>Type</th>
<th>Description</th>
<th>Available on</th>
</tr>
</thead>
<tbody>
<tr class="odd">
<td><code>runtime.ruby.class_count</code></td>
<td><code>gauge</code></td>
<td>Number of classes in memory space.</td>
<td>CRuby</td>
</tr>
<tr class="even">
<td><code>runtime.ruby.gc.*</code></td>
<td><code>gauge</code></td>
<td>Garbage collection statistics: collected from <code>GC.stat</code>.</td>
<td>All runtimes</td>
</tr>
<tr class="odd">
<td><code>runtime.ruby.yjit.*</code></td>
<td><code>gauge</code></td>
<td>YJIT statistics collected from <code>RubyVM::YJIT.runtime_stats</code>.</td>
<td>CRuby (if enabled)</td>
</tr>
<tr class="even">
<td><code>runtime.ruby.thread_count</code></td>
<td><code>gauge</code></td>
<td>Number of threads.</td>
<td>All runtimes</td>
</tr>
<tr class="odd">
<td><code>runtime.ruby.global_constant_state</code></td>
<td><code>gauge</code></td>
<td>Global constant cache generation.</td>
<td>CRuby ≤ 3.1</td>
</tr>
<tr class="even">
<td><code>runtime.ruby.global_method_state</code></td>
<td><code>gauge</code></td>
<td><a href="https://tenderlovemaking.com/2015/12/23/inline-caching-in-mri.html">Global method cache generation.</a></td>
<td><a href="https://docs.ruby-lang.org/en/3.0.0/NEWS_md.html#label-Implementation+improvements">CRuby 2.x</a></td>
</tr>
<tr class="odd">
<td><code>runtime.ruby.constant_cache_invalidations</code></td>
<td><code>gauge</code></td>
<td>Constant cache invalidations.</td>
<td>CRuby ≥ 3.2</td>
</tr>
<tr class="even">
<td><code>runtime.ruby.constant_cache_misses</code></td>
<td><code>gauge</code></td>
<td>Constant cache misses.</td>
<td>CRuby ≥ 3.2</td>
</tr>
</tbody>
</table>
<p>In addition, all metrics include the following tags:</p>
<table>
<thead>
<tr class="header">
<th>Name</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr class="odd">
<td><code>language</code></td>
<td>Programming language traced. (e.g. <code>ruby</code>)</td>
</tr>
<tr class="even">
<td><code>service</code></td>
<td>List of services this associated with this metric.</td>
</tr>
</tbody>
</table>
<h3 id="opentracing">OpenTracing</h3>
<p>For setting up Datadog with OpenTracing, see our <a href="#configuring-opentracing">Configuring OpenTracing</a> section for details.</p>
<p><strong>Configuring Datadog tracer settings</strong></p>
<p>The underlying Datadog tracer can be configured by passing options (which match <code>Datadog::Tracer</code>) when configuring the global tracer:</p>
<div class="sourceCode" id="cb111"><pre class="sourceCode ruby"><code class="sourceCode ruby"><span id="cb111-1"><a href="#cb111-1" aria-hidden="true"></a><span class="co"># Where `options` is a Hash of options provided to Datadog::Tracer</span></span>
<span id="cb111-2"><a href="#cb111-2" 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(**options)</span></code></pre></div>
<p>It can also be configured by using <code>Datadog.configure</code> described in the <a href="#additional-configuration">Additional Configuration</a> section.</p>
<p><strong>Activating and configuring integrations</strong></p>
<p>By default, configuring OpenTracing with Datadog will not automatically activate any additional instrumentation provided by Datadog. You will only receive spans and traces from OpenTracing instrumentation you have in your application.</p>
<p>However, additional instrumentation provided by Datadog can be activated alongside OpenTracing using <code>Datadog.configure</code>, which can be used to enhance your tracing further. To activate this, see <a href="#integration-instrumentation">Integration instrumentation</a> for more details.</p>
<p><strong>Supported serialization formats</strong></p>
<table>
<colgroup>
<col style="width: 48%">
<col style="width: 16%">
<col style="width: 35%">
</colgroup>
<thead>
<tr class="header">
<th>Type</th>
<th>Supported?</th>
<th>Additional information</th>
</tr>
</thead>
<tbody>
<tr class="odd">
<td><code>OpenTracing::FORMAT_TEXT_MAP</code></td>
<td>Yes</td>
<td></td>
</tr>
<tr class="even">
<td><code>OpenTracing::FORMAT_RACK</code></td>
<td>Yes</td>
<td>Because of the loss of resolution in the Rack format, please note that baggage items with names containing either upper case characters or <code>-</code> will be converted to lower case and <code>_</code> in a round-trip respectively. We recommend avoiding these characters or accommodating accordingly on the receiving end.</td>
</tr>
<tr class="odd">
<td><code>OpenTracing::FORMAT_BINARY</code></td>
<td>No</td>
<td></td>
</tr>
</tbody>
</table>
<h3 id="profiling">Profiling</h3>
<p><code>ddtrace</code> can produce profiles that measure method-level application resource usage within production environments. These profiles can give insight into resources spent in Ruby code outside of existing trace instrumentation.</p>
<p><strong>Setup</strong></p>
<p>To get started with profiling, follow the <a href="https://docs.datadoghq.com/tracing/profiler/enabling/ruby/">Enabling the Ruby Profiler</a> guide.</p>
<h4 id="troubleshooting">Troubleshooting</h4>
<p>If you run into issues with profiling, please check the <a href="https://docs.datadoghq.com/tracing/profiler/profiler_troubleshooting/?code-lang=ruby">Profiler Troubleshooting Guide</a>.</p>
<h4 id="profiling-resque-jobs">Profiling Resque jobs</h4>
<p>When profiling <a href="https://github.com/resque/resque">Resque</a> jobs, you should set the <code>RUN_AT_EXIT_HOOKS=1</code> option described in the <a href="https://github.com/resque/resque/blob/v2.0.0/docs/HOOKS.md#worker-hooks">Resque</a> documentation.</p>
<p>Without this flag, profiles for short-lived Resque jobs will not be available as Resque kills worker processes before they have a chance to submit this information.</p>
<h2 id="known-issues-and-suggested-configurations">Known issues and suggested configurations</h2>
<h3 id="payload-too-large">Payload too large</h3>
<p>By default, Datadog limits the size of trace payloads to prevent memory overhead within instrumented applications. As a result, traces containing thousands of operations may not be sent to Datadog.</p>
<p>If traces are missing, enable <a href="#debugging-and-diagnostics">debug mode</a> to check if messages containing <code>"Dropping trace. Payload too large"</code> are logged.</p>
<p>Since debug mode is verbose, <strong>Datadog does not recommend leaving this enabled or enabling this in production.</strong> Disable it after confirming. You can inspect the <a href="https://docs.datadoghq.com/agent/guide/agent-log-files/">Datadog Agent logs</a> for similar messages.</p>
<p>If you have confirmed that traces are dropped due to large payloads, then enable the <a href="#additional-configuration">partial_flush</a> setting to break down large traces into smaller chunks.</p>
<h3 id="stack-level-too-deep">Stack level too deep</h3>
<p>Datadog tracing collects trace data by adding instrumentation into other common libraries (e.g. Rails, Rack, etc.) Some libraries provide APIs to add this instrumentation, but some do not. In order to add instrumentation into libraries lacking an instrumentation API, Datadog uses a technique called “monkey-patching” to modify the code of that library.</p>
<p>In Ruby version 1.9.3 and earlier, “monkey-patching” often involved the use of <a href="https://ruby-doc.org/core-3.0.0/Module.html#method-i-alias_method"><code>alias_method</code></a>, also known as <em>method rewriting</em>, to destructively replace existing Ruby methods. However, this practice would often create conflicts &amp; errors if two libraries attempted to “rewrite” the same method. (e.g. two different APM packages trying to instrument the same method.)</p>
<p>In Ruby 2.0, the <a href="https://ruby-doc.org/core-3.0.0/Module.html#method-i-prepend"><code>Module#prepend</code></a> feature was introduced. This feature avoids destructive method rewriting and allows multiple “monkey patches” on the same method. Consequently, it has become the safest, preferred means to “monkey patch” code.</p>
<p>Datadog instrumentation almost exclusively uses the <code>Module#prepend</code> feature to add instrumentation non-destructively. However, some other libraries (typically those supporting Ruby &lt; 2.0) still use <code>alias_method</code> which can create conflicts with Datadog instrumentation, often resulting in <code>SystemStackError</code> or <code>stack level too deep</code> errors.</p>
<p>As the implementation of <code>alias_method</code> exists within those libraries, Datadog generally cannot fix them. However, some libraries have known workarounds:</p>
<ul>
<li>
<code>rack-mini-profiler</code>: <a href="https://github.com/MiniProfiler/rack-mini-profiler#nethttp-stack-level-too-deep-errors">Net::HTTP stack level too deep errors</a>.</li>
</ul>
<p>For libraries without a known workaround, consider removing the library using <code>alias</code> or <code>Module#alias_method</code> or separating libraries into different environments for testing.</p>
<p>For any further questions or to report an occurrence of this issue, please <a href="https://docs.datadoghq.com/help">reach out to Datadog support</a></p>
<h3 id="resque-workers-hang-on-exit">Resque workers hang on exit</h3>
<p>Resque’s default of forking a process per job can, in rare situations, result in resque processes hanging on exit when instrumented with ddtrace.</p>
<p>As a workaround, we recommend setting the <code>FORK_PER_JOB</code> environment variable to <code>false</code> to disable this behavior.</p>
<p>See <a href="https://github.com/DataDog/dd-trace-rb/issues/3015">this issue</a> for a discussion of the problem.</p>
<!---->
</body>
</html>