Method: Datadog::Tracing::Tracer#trace

Defined in:
lib/datadog/tracing/tracer.rb

#trace(name, continue_from: nil, on_error: nil, resource: nil, service: nil, start_time: nil, tags: nil, type: nil, span_type: nil, _context: nil) {|span_op, trace_op| ... } ⇒ Object, Datadog::Tracing::SpanOperation

Return a span_op and trace_op that will trace an operation called ‘name`.

You could trace your code using a do-block like:

“‘ tracer.trace(’web.request’) do |span_op, trace_op|

span_op.service = 'my-web-site'
span_op.resource = '/'
span_op.set_tag('http.method', request.request_method)
do_something()

end “‘

The #trace method can also be used without a block in this way: “‘ span_op = tracer.trace(’web.request’, service: ‘my-web-site’) do_something() span_op.finish() “‘

Remember that in this case, calling SpanOperation#finish is mandatory.

When a Trace is started, #trace will store the created span; subsequent spans will become its children and will inherit some properties: “‘ parent = tracer.trace(’parent’) # has no parent span child = tracer.trace(‘child’) # is a child of ‘parent’ child.finish() parent.finish() parent2 = tracer.trace(‘parent2’) # has no parent span parent2.finish() “‘

rubocop:disable Lint/UnderscorePrefixedVariableName rubocop:disable Metrics/MethodLength

Parameters:

  • name (String) —

    Span operation name. See / Primary Operations in Services.

  • continue_from (Datadog::Tracing::TraceDigest) (defaults to: nil) —

    continue a trace from a Datadog::Tracing::TraceDigest. Used for linking traces that are executed asynchronously.

  • on_error (Proc) (defaults to: nil) —

    a block that overrides error handling behavior for this operation.

  • resource (String) (defaults to: nil) —

    the resource this span refers, or ‘name` if it’s missing

  • service (String) (defaults to: nil) —

    the service name for this span.

  • start_time (Time) (defaults to: nil) —

    time which the span should have started.

  • tags (Hash<String,String>) (defaults to: nil) —

    extra tags which should be added to the span.

  • type (String) (defaults to: nil) —

    the type of the span. See Metadata::Ext::AppTypes.

Yields:

  • Optional block where new newly created SpanOperation captures the execution.

Yield Parameters:

Returns:



123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
 
# File 'lib/datadog/tracing/tracer.rb', line 123

def trace(
  name,
  continue_from: nil,
  on_error: nil,
  resource: nil,
  service: nil,
  start_time: nil,
  tags: nil,
  type: nil,
  span_type: nil,
  _context: nil,
  &block
)
  return skip_trace(name, &block) unless enabled

  context, trace = nil

  # Resolve the trace
  begin
    context = _context || call_context
    active_trace = context.active_trace
    trace = if continue_from || active_trace.nil?
              start_trace(continue_from: continue_from)
            else
              active_trace
            end
  rescue StandardError => e
    Datadog.logger.debug { "Failed to trace: #{e}" }

    # Tracing failed: fallback and run code without tracing.
    return skip_trace(name, &block)
  end

  # Activate and start the trace
  if block
    context.activate!(trace) do
      start_span(
        name,
        on_error: on_error,
        resource: resource,
        service: service,
        start_time: start_time,
        tags: tags,
        type: span_type || type,
        _trace: trace,
        &block
      )
    end
  else
    # Setup trace activation/deactivation
    manual_trace_activation!(context, trace)

    # Return the new span
    start_span(
      name,
      on_error: on_error,
      resource: resource,
      service: service,
      start_time: start_time,
      tags: tags,
      type: span_type || type,
      _trace: trace
    )
  end
end