Class: Datadog::Tracing::Tracer
- Inherits:
-
Object
- Object
- Datadog::Tracing::Tracer
- Defined in:
- lib/datadog/tracing/tracer.rb
Overview
A Tracer keeps track of the time spent by an application processing a single operation. For example, a trace can be used to track the entire time spent processing a complicated web request. Even though the request may require multiple resources and machines to handle the request, all of these function calls and sub-requests would be encapsulated within a single trace.
Defined Under Namespace
Classes: TraceCompleted
Instance Attribute Summary collapse
-
#default_service ⇒ Object
Returns the value of attribute default_service.
-
#enabled ⇒ Object
Returns the value of attribute enabled.
-
#provider ⇒ Object
readonly
Returns the value of attribute provider.
-
#sampler ⇒ Object
readonly
Returns the value of attribute sampler.
-
#span_sampler ⇒ Object
readonly
Returns the value of attribute span_sampler.
-
#tags ⇒ Object
readonly
Returns the value of attribute tags.
-
#trace_flush ⇒ Object
readonly
Returns the value of attribute trace_flush.
-
#writer ⇒ Object
Returns the value of attribute writer.
Instance Method Summary collapse
-
#active_correlation(key = nil) ⇒ Datadog::Tracing::Correlation::Identifier
Information about the currently active trace.
-
#active_span(key = nil) ⇒ Datadog::Tracing::SpanOperation?
The active, unfinished span, representing the currently instrumented application section.
-
#active_trace(key = nil) ⇒ Datadog::Tracing::TraceSegment?
The active, unfinished trace, representing the current instrumentation context.
-
#continue_trace!(digest, key = nil) { ... } ⇒ Object, Datadog::Tracing::TraceOperation
Setup a new trace to continue from where another trace left off.
-
#initialize(trace_flush: Flush::Finished.new, context_provider: DefaultContextProvider.new, default_service: Core::Environment::Ext::FALLBACK_SERVICE_NAME, enabled: true, sampler: Sampling::PrioritySampler.new( base_sampler: Sampling::AllSampler.new, post_sampler: Sampling::RuleSampler.new ), span_sampler: Sampling::Span::Sampler.new, tags: {}, writer: Writer.new) ⇒ Tracer
constructor
Initialize a new Tracer used to create, sample and submit spans that measure the time of sections of code.
-
#sample_trace(trace_op) ⇒ Object
Sample a span, tagging the trace as appropriate.
-
#set_tags(tags) ⇒ Object
Set the given key / value tag pair at the tracer level.
-
#shutdown! ⇒ Object
Shorthand that calls the ‘shutdown!` method of a registered worker.
- #trace(name, continue_from: nil, on_error: nil, resource: nil, service: nil, start_time: nil, tags: nil, type: nil, id: nil) {|span_op, trace_op| ... } ⇒ Object, Datadog::Tracing::SpanOperation
Constructor Details
#initialize(trace_flush: Flush::Finished.new, context_provider: DefaultContextProvider.new, default_service: Core::Environment::Ext::FALLBACK_SERVICE_NAME, enabled: true, sampler: Sampling::PrioritySampler.new( base_sampler: Sampling::AllSampler.new, post_sampler: Sampling::RuleSampler.new ), span_sampler: Sampling::Span::Sampler.new, tags: {}, writer: Writer.new) ⇒ Tracer
Initialize a new Datadog::Tracing::Tracer used to create, sample and submit spans that measure the time of sections of code.
50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 |
# File 'lib/datadog/tracing/tracer.rb', line 50 def initialize( trace_flush: Flush::Finished.new, context_provider: DefaultContextProvider.new, default_service: Core::Environment::Ext::FALLBACK_SERVICE_NAME, enabled: true, sampler: Sampling::PrioritySampler.new( base_sampler: Sampling::AllSampler.new, post_sampler: Sampling::RuleSampler.new ), span_sampler: Sampling::Span::Sampler.new, tags: {}, writer: Writer.new ) @trace_flush = trace_flush @default_service = default_service @enabled = enabled @provider = context_provider @sampler = sampler @span_sampler = span_sampler @tags = @writer = writer end |
Instance Attribute Details
#default_service ⇒ Object
Returns the value of attribute default_service.
33 34 35 |
# File 'lib/datadog/tracing/tracer.rb', line 33 def default_service @default_service end |
#enabled ⇒ Object
Returns the value of attribute enabled.
33 34 35 |
# File 'lib/datadog/tracing/tracer.rb', line 33 def enabled @enabled end |
#provider ⇒ Object (readonly)
Returns the value of attribute provider.
26 27 28 |
# File 'lib/datadog/tracing/tracer.rb', line 26 def provider @provider end |
#sampler ⇒ Object (readonly)
Returns the value of attribute sampler.
26 27 28 |
# File 'lib/datadog/tracing/tracer.rb', line 26 def sampler @sampler end |
#span_sampler ⇒ Object (readonly)
Returns the value of attribute span_sampler.
26 27 28 |
# File 'lib/datadog/tracing/tracer.rb', line 26 def span_sampler @span_sampler end |
#tags ⇒ Object (readonly)
Returns the value of attribute tags.
26 27 28 |
# File 'lib/datadog/tracing/tracer.rb', line 26 def @tags end |
#trace_flush ⇒ Object (readonly)
Returns the value of attribute trace_flush.
26 27 28 |
# File 'lib/datadog/tracing/tracer.rb', line 26 def trace_flush @trace_flush end |
#writer ⇒ Object
Returns the value of attribute writer.
33 34 35 |
# File 'lib/datadog/tracing/tracer.rb', line 33 def writer @writer end |
Instance Method Details
#active_correlation(key = nil) ⇒ Datadog::Tracing::Correlation::Identifier
Information about the currently active trace.
The most common use cases are tagging log messages and metrics.
229 230 231 232 233 234 235 |
# File 'lib/datadog/tracing/tracer.rb', line 229 def active_correlation(key = nil) trace = active_trace(key) return Datadog::Tracing::Correlation::Identifier.new unless trace trace.to_correlation end |
#active_span(key = nil) ⇒ Datadog::Tracing::SpanOperation?
The active, unfinished span, representing the currently instrumented application section.
The active span belongs to an Datadog::Tracing.active_trace.
218 219 220 221 |
# File 'lib/datadog/tracing/tracer.rb', line 218 def active_span(key = nil) trace = active_trace(key) trace.active_span if trace end |
#active_trace(key = nil) ⇒ Datadog::Tracing::TraceSegment?
The active, unfinished trace, representing the current instrumentation context.
The active trace is fiber-local.
207 208 209 |
# File 'lib/datadog/tracing/tracer.rb', line 207 def active_trace(key = nil) call_context(key).active_trace end |
#continue_trace!(digest, key = nil) { ... } ⇒ Object, Datadog::Tracing::TraceOperation
Setup a new trace to continue from where another trace left off.
Used to continue distributed or async traces.
248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 |
# File 'lib/datadog/tracing/tracer.rb', line 248 def continue_trace!(digest, key = nil, &block) # Only accept {TraceDigest} as a digest. # Otherwise, create a new execution context. digest = nil unless digest.is_a?(TraceDigest) # Start a new trace from the digest context = call_context(key) original_trace = active_trace(key) trace = start_trace(continue_from: digest) # If block hasn't been given; we need to manually deactivate # this trace. Subscribe to the trace finished event to do this. subscribe_trace_deactivation!(context, trace, original_trace) unless block context.activate!(trace, &block) end |
#sample_trace(trace_op) ⇒ Object
Sample a span, tagging the trace as appropriate.
266 267 268 269 270 271 272 273 274 |
# File 'lib/datadog/tracing/tracer.rb', line 266 def sample_trace(trace_op) begin @sampler.sample!(trace_op) rescue StandardError => e SAMPLE_TRACE_LOG_ONLY_ONCE.run do Datadog.logger.warn { "Failed to sample trace: #{e.class.name} #{e} at #{Array(e.backtrace).first}" } end end end |
#set_tags(tags) ⇒ Object
Set the given key / value tag pair at the tracer level. These tags will be appended to each span created by the tracer. Keys and values must be strings.
195 196 197 198 |
# File 'lib/datadog/tracing/tracer.rb', line 195 def () = .collect { |k, v| [k.to_s, v] }.to_h @tags = @tags.merge() end |
#shutdown! ⇒ Object
Shorthand that calls the ‘shutdown!` method of a registered worker. It’s useful to ensure that the Trace Buffer is properly flushed before shutting down the application.
307 308 309 310 311 |
# File 'lib/datadog/tracing/tracer.rb', line 307 def shutdown! return unless @enabled @writer.stop if @writer end |
#trace(name, continue_from: nil, on_error: nil, resource: nil, service: nil, start_time: nil, tags: nil, type: nil, id: 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 Metrics/MethodLength
125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 |
# File 'lib/datadog/tracing/tracer.rb', line 125 def trace( name, continue_from: nil, on_error: nil, resource: nil, service: nil, start_time: nil, tags: nil, type: nil, id: nil, &block ) return skip_trace(name, &block) unless enabled # Resolve the trace begin 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: , type: type, _trace: trace, id: id, &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: , type: type, _trace: trace, id: id ) end end |