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, 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 (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.



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

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

Instance Attribute Details

#project ⇒ String (readonly)

The project ID for this trace.

Returns:

  • (String) 


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

def project
  @project
end

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

The context for this trace.

Returns:

  • (Stackdriver::Core::TraceContext) 


131
132
133
 
# File 'lib/google/cloud/trace/trace_record.rb', line 131

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.



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

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 == 0
  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}) 


148
149
150
 
# File 'lib/google/cloud/trace/trace_record.rb', line 148

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-id"
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.



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

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 == 0
  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) 


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

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-id"
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.



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

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}) 


158
159
160
 
# File 'lib/google/cloud/trace/trace_record.rb', line 158

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:



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

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,
    trace_id: trace_id,
    spans: span_protos
end

#trace_id ⇒ String

The ID string for the trace.

Returns:

  • (String) 


138
139
140
 
# File 'lib/google/cloud/trace/trace_record.rb', line 138

def trace_id
  trace_context.trace_id
end