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 = my_get_rack_environment
trace_context = Stackdriver::Core::TraceContext.parse_rack_env env

trace = Google::Cloud::Trace.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.



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

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) 


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

def project
  @project
end

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

The context for this trace.

Returns:

  • (Stackdriver::Core::TraceContext) 


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

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.



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

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


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

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 = Google::Cloud::Trace.new trace_context
span = trace.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.



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

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) 


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

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 = Google::Cloud::Trace.new trace_context
trace.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.



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

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


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

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:



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

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) 


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

def trace_id
  trace_context.trace_id
end