Class: Brut::Instrumentation::OpenTelemetry

Inherits:
Object
  • Object
show all
Defined in:
lib/brut/instrumentation/open_telemetry.rb

Overview

Class to interact with the OpenTelemetry standard in a simpler way than the provided Ruby gem does. In general, you should use this class via Brut.container.instrumentation, and you should not use the OpenTelemetry ruby library directly. You probably wouldn't want to, anyway.

Defined Under Namespace

Classes: NormalizedAttributes, Span

Instance Method Summary collapse

Instance Method Details

#add_attributes(attributes) ⇒ Object

Adds attributes to the span, converting the hash or keyword arguments to strings. This will use the app's Otel prefix for all attributes, so you do not have to prefix them. If you need to set standard attributes, you should use #add_prefixed_attributes instead.

Parameters:

  • attributes (Hash) —

    any attributes to attach to the event.



76
77
78
79
 
# File 'lib/brut/instrumentation/open_telemetry.rb', line 76

def add_attributes(attributes)
  current_span = OpenTelemetry::Trace.current_span
  current_span.add_attributes(NormalizedAttributes.new(:detect,attributes).to_h)
end

#add_event(name, **attributes) ⇒ Object

Adds an event to the current span

Parameters:

  • name (String) —

    the name of the event. Should not contain dynamic information.

  • attributes (Hash) —

    any attributes to attach to the event.



37
38
39
40
41
42
43
44
 
# File 'lib/brut/instrumentation/open_telemetry.rb', line 37

def add_event(name,**attributes)
  explicit_attributes = attributes.delete(:attributes) || {}
  timestamp = attributes.delete(:timestamp)
  current_span = OpenTelemetry::Trace.current_span
  current_span.add_event(name,
                         attributes: NormalizedAttributes.new(nil,attributes.merge(explicit_attributes)).to_h,
                         timestamp:)
end

#add_prefixed_attributes(prefix, attributes) ⇒ Object

Adds attributes to the span, prefixing each key with the given prefix, then converting the hash or keyword arguments to strings. For example, if the prefix is 'my_app' and you add the attributes 'type' and 'reason', the actual attribute names will be 'my_app.type' and 'my_app.reason'.

See Also:



84
85
86
87
88
89
 
# File 'lib/brut/instrumentation/open_telemetry.rb', line 84

def add_prefixed_attributes(prefix,attributes)
  current_span = OpenTelemetry::Trace.current_span
  current_span.add_attributes(
    NormalizedAttributes.new(prefix,attributes).to_h
  )
end

#record_and_reraise_exception!(ex, attributes = nil) ⇒ Object

Record an exception and re-raise it. This is useful if you want the exception recorded as part of the parent span, but still plan to let it raise. Don't do this for every exception you intend to raise.

Parameters:

  • ex (Exception) —

    the exception to record.

  • attributes (Hash) (defaults to: nil) —

    any attributes to attach that will show up in your OTel provider

Raises:

  • (Exception) —

    the exception passed in.



66
67
68
69
 
# File 'lib/brut/instrumentation/open_telemetry.rb', line 66

def record_and_reraise_exception!(ex,attributes=nil)
  reecord_exception(ex,attributes)
  raise ex
end

#record_exception(ex, attributes = nil) ⇒ Object

Record an exception. In general, use this only if:

  • You need to have the parent span record this particular exception
  • You are not going to re-raise the exception.

Otherwise, look at #record_and_reraise_exception!.

Parameters:

  • ex (Exception) —

    the exception to record.

  • attributes (Hash) (defaults to: nil) —

    any attributes to attach that will show up in your OTel provider



55
56
57
58
 
# File 'lib/brut/instrumentation/open_telemetry.rb', line 55

def record_exception(ex,attributes=nil)
  current_span = OpenTelemetry::Trace.current_span
  current_span.record_exception(ex,attributes: NormalizedAttributes.new(nil,attributes).to_h)
end

#span(name, **attributes) {|Brut::Instrumentation::OpenTelemetry::Span| ... } ⇒ Object

Create a span around the given block of code.

example, you could call this the method name, but should not include parameters in the name.

Parameters:

  • name (String) —

    the name of the span. Should be specific to the code being wrapped, but not contain dynamic information. For

  • attributes (Hash<String|Symbol,Object>) —

    Hash of attributes to include in this span. This is as if you called Brut::Instrumentation::OpenTelemetry::Span#add_attributes as the first line of the block. There is a special attribute named prefix: that will control how attributes are prefixed. If it is missing, the app's configured OTel prefix is used. If it is sent to false, no prefixing is done. Otherwise, the provided value is used as the prefix. Generally, you don't want to set this so your app's prefix is used. Also note that the keys and values are automatically converted to primitive types, so you can use whatever makes sense. Just know that for rich objects to_s will be called.

Yields:

Yield Parameters:

Yield Returns:

  • (Object) —

    Whatever is returned from the block is returned by this method

Returns:

  • (Object) —

    Whatever is returned from the block, unless an exception is raised.

Raises:

  • (Exception) —

    if the block raises an exception, that exception will be raised, however record_exception will be called.



19
20
21
22
23
24
25
26
27
28
29
30
31
32
 
# File 'lib/brut/instrumentation/open_telemetry.rb', line 19

def span(name,**attributes,&block)
  result = nil
  normalized_attributes = NormalizedAttributes.new(:detect,attributes).to_h
  Brut.container.tracer.in_span(name, attributes: normalized_attributes) do |span|
    wrapped_span = Span.new(span)
    begin
      result = block.(wrapped_span)
    rescue => ex
      span.record_exception(ex)
      raise
    end
  end
  result
end