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
 
# 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 { rand(1..0xffffffffffffffff) }
end

Instance Attribute Details

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

The project ID for this trace.

Returns:

  • (String) 


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

def project_id
  @project_id
end

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

The context for this trace.

Returns:

  • (Stackdriver::Core::TraceContext) 


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

def trace_context
  @trace_context
end

Class Method Details

.from_grpc(trace_proto) ⇒ Trace?

Create a new Trace object from a trace protobuf.

Parameters:

  • trace_proto (Google::Cloud::Trace::V1::Trace) —

    The trace protobuf from the V1 gRPC Trace API.

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


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

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) (defaults to: nil) —

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

  • parent_span_id (Integer) (defaults to: 0) —

    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) (defaults to: SpanKind::UNSPECIFIED) —

    The kind of span. Optional.

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

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

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

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

  • labels (Hash{String=>String}) (defaults to: {}) —

    The span properties. Optional (defaults to empty).

Returns:

  • (TraceSpan) —

    The created span.



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

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) 


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"
trace_record.in_span "root_span" do |span|
  # Do stuff...
end

Parameters:

  • name (String) —

    The name of the span.

  • kind (SpanKind) (defaults to: SpanKind::UNSPECIFIED) —

    The kind of span. Optional.

  • labels (Hash{String=>String}) (defaults to: {}) —

    The span properties. Optional (defaults to empty).

Returns:

  • (TraceSpan) —

    The created span.



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

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


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

def root_spans
  @root_spans.dup
end

#to_grpc ⇒ Google::Cloud::Trace::V1::Trace

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

Returns:

  • (Google::Cloud::Trace::V1::Trace) —

    The generated protobuf.



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::Cloud::Trace::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) 


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

def trace_id
  trace_context.trace_id
end