Class: Google::Cloud::Trace::TraceRecord

Inherits:
Object
  • Object
show all
Defined in:
lib/google/cloud/trace/trace_record.rb

Overview

Trace represents an entire trace record.

A trace has an ID and contains a forest of spans. The trace object methods may be used to walk or manipulate the set of spans.

Examples:

require "google/cloud/trace"

env = {}
trace_context = Stackdriver::Core::TraceContext.parse_rack_env env

trace = Google::Cloud::Trace::TraceRecord.new "my-project",
                                              trace_context
span = trace.create_span "root_span"
subspan = span.create_span "subspan"

trace_proto = trace.to_grpc

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(project_id, trace_context = nil, span_id_generator: nil) ⇒ TraceRecord

Create an empty Trace object. If a trace context is provided, it is used to locate this trace within that context.

Parameters:

  • project_id (String) —

    The ID of the project containing this trace.

  • trace_context (Stackdriver::Core::TraceContext) (defaults to: nil) —

    The context within which to locate this trace (i.e. sets the trace ID and the context parent span, if present.) If no context is provided, a new trace with a new trace ID is created.



54
55
56
57
58
59
60
61
 
# File 'lib/google/cloud/trace/trace_record.rb', line 54

def initialize project_id, trace_context = nil, span_id_generator: nil
  @project_id = project_id
  @trace_context = trace_context || Stackdriver::Core::TraceContext.new
  @root_spans = []
  @spans_by_id = {}
  @span_id_generator =
    span_id_generator || ::Proc.new { rand(1..0xffffffffffffffff) }
end

Instance Attribute Details

#project_id ⇒ String (readonly) Also known as: project

The project ID for this trace.

Returns:

  • (String) 


125
126
127
 
# File 'lib/google/cloud/trace/trace_record.rb', line 125

def project_id
  @project_id
end

#trace_context ⇒ Stackdriver::Core::TraceContext (readonly)

The context for this trace.

Returns:

  • (Stackdriver::Core::TraceContext) 


133
134
135
 
# File 'lib/google/cloud/trace/trace_record.rb', line 133

def trace_context
  @trace_context
end

Class Method Details

.from_grpc(trace_proto) ⇒ Trace?

Create a new Trace object from a trace protobuf.

Parameters:

Returns:

  • (Trace, nil) —

    A corresponding Trace object, or nil if the proto does not represent an existing trace object.



84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
 
# File 'lib/google/cloud/trace/trace_record.rb', line 84

def self.from_grpc trace_proto
  trace_id = trace_proto.trace_id.to_s
  return nil if trace_id.empty?

  span_protos = trace_proto.spans
  parent_span_ids = find_root_span_ids span_protos

  span_id = parent_span_ids.size == 1 ? parent_span_ids.first : 0
  span_id = nil if span_id.zero?
  tc = Stackdriver::Core::TraceContext.new trace_id: trace_id,
                                           span_id: span_id
  trace = new trace_proto.project_id, tc

  until parent_span_ids.empty?
    parent_span_ids = trace.add_span_protos span_protos, parent_span_ids
  end
  trace
end

Instance Method Details

#all_spans ⇒ Array{TraceSpan}

Returns an array of all spans in this trace, not in any particular order

Returns:

  • (Array{TraceSpan}) 


150
151
152
 
# File 'lib/google/cloud/trace/trace_record.rb', line 150

def all_spans
  @spans_by_id.values
end

#create_span(name, span_id: nil, parent_span_id: 0, kind: SpanKind::UNSPECIFIED, start_time: nil, end_time: nil, labels: {}) ⇒ TraceSpan

Creates a new span in this trace.

Examples:

require "google/cloud/trace"

trace_record = Google::Cloud::Trace::TraceRecord.new "my-project"
span = trace_record.create_span "root_span"

Parameters:

  • name (String) —

    The name of the span.

  • span_id (Integer) —

    The numeric ID of the span, or nil to generate a new random unique ID. Optional (defaults to nil).

  • parent_span_id (Integer) —

    The span ID of the parent span, or 0 if this should be a new root span within the context. Note that a root span would not necessarily end up with a parent ID of 0 if the trace context specifies a different context span ID. Optional (defaults to 0).

  • kind (SpanKind) —

    The kind of span. Optional.

  • start_time (Time) —

    The starting timestamp, or nil if not yet specified. Optional (defaults to nil).

  • end_time (Time) —

    The ending timestamp, or nil if not yet specified. Optional (defaults to nil).

  • labels (Hash{String=>String}) —

    The span properties. Optional (defaults to empty).

Returns:

  • (TraceSpan) —

    The created span.



190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
 
# File 'lib/google/cloud/trace/trace_record.rb', line 190

def create_span name, span_id: nil, parent_span_id: 0,
                kind: SpanKind::UNSPECIFIED,
                start_time: nil, end_time: nil,
                labels: {}
  parent_span_id = parent_span_id.to_i
  parent_span_id = trace_context.span_id.to_i if parent_span_id.zero?
  parent_span = @spans_by_id[parent_span_id]
  if parent_span
    parent_span.create_span name,
                            span_id: span_id,
                            kind: kind,
                            start_time: start_time,
                            end_time: end_time,
                            labels: labels
  else
    internal_create_span nil, span_id, parent_span_id, name, kind,
                         start_time, end_time, labels
  end
end

#eql?(other) ⇒ Boolean Also known as: ==

Standard value equality check for this object.

Parameters:

  • other (Object) —

    Object to compare with

Returns:

  • (Boolean) 


69
70
71
72
73
 
# File 'lib/google/cloud/trace/trace_record.rb', line 69

def eql? other
  other.is_a?(Google::Cloud::Trace::TraceRecord) &&
    trace_context == other.trace_context &&
    @spans_by_id == other.instance_variable_get(:@spans_by_id)
end

#in_span(name, kind: SpanKind::UNSPECIFIED, labels: {}) ⇒ TraceSpan

Creates a root span around the given block. Automatically populates the start and end timestamps. The span (with start time but not end time populated) is yielded to the block.

Examples:

require "google/cloud/trace"

trace_record = Google::Cloud::Trace::TraceRecord.new "my-project"
trace_record.in_span "root_span" do |span|
  # Do stuff...
end

Parameters:

  • name (String) —

    The name of the span.

  • kind (SpanKind) —

    The kind of span. Optional.

  • labels (Hash{String=>String}) —

    The span properties. Optional (defaults to empty).

Returns:

  • (TraceSpan) —

    The created span.



229
230
231
232
233
234
235
 
# File 'lib/google/cloud/trace/trace_record.rb', line 229

def in_span name, kind: SpanKind::UNSPECIFIED, labels: {}
  span = create_span name, kind: kind, labels: labels
  span.start!
  yield span
ensure
  span.finish!
end

#root_spans ⇒ Array{TraceSpan}

Returns an array of all root spans in this trace, not in any particular order

Returns:

  • (Array{TraceSpan}) 


160
161
162
 
# File 'lib/google/cloud/trace/trace_record.rb', line 160

def root_spans
  @root_spans.dup
end

#to_grpc ⇒ Google::Devtools::Cloudtrace::V1::Trace

Convert this Trace object to an equivalent Trace protobuf suitable for the V1 gRPC Trace API.

Returns:



110
111
112
113
114
115
116
117
118
 
# File 'lib/google/cloud/trace/trace_record.rb', line 110

def to_grpc
  span_protos = @spans_by_id.values.map do |span|
    span.to_grpc trace_context.span_id.to_i
  end
  Google::Devtools::Cloudtrace::V1::Trace.new \
    project_id: project_id,
    trace_id: trace_id,
    spans: span_protos
end

#trace_id ⇒ String

The ID string for the trace.

Returns:

  • (String) 


140
141
142
 
# File 'lib/google/cloud/trace/trace_record.rb', line 140

def trace_id
  trace_context.trace_id
end