Reference documentation and code samples for the stackdriver-core class Stackdriver::Core::TraceContext.
A Stackdriver trace context links the current request into a performance
trace, and communicates tracing options between related requests. This
functionality is used by the Stackdriver diagnostics libraries
(including google-cloud-trace, google-cloud-logging, and other rubygems)
that integrate with the tracing service.
Most applications will not need to use the TraceContext class directly.
The Stackdriver libraries use it internally to store and propagate
context information.
Inherits
Object
Methods
.get
defself.get()->TraceContext,nil
Returns the current thread's trace context, ornilif no trace
context has been set.
Obtains a TraceContext from the given Rack environment. This should
be used by any service that wants to obtain the TraceContext for a
Rack request. If a new trace context is generated in the process, it
is memoized into the Rack environment so subsequent services will get
the same context.
Specifically, the following steps are attempted in order:
Attempts to use any memoized context previously obtained.
Attempts to parse the trace context header.
Creates a new trace context with a random trace ID.
Furthermore, if a block is given, it is provided with an opportunity
to modify the trace context. The current trace context and the Rack
environment is passed to the block, and its result is used as the
final trace context. The final context is memoized back into the
Rack environment.
Attempts to parse the given string as a trace context representation.
Expects the form<traceid>[/<spanid>][;o=<options>], which is the
form used in the trace context header. Returns either the parsed
trace context, ornilif the string was malformed.
trace_id(String)(defaults to: nil)— The trace ID as a hex string. If nil or
omitted, a new random Trace ID will be generated, and this
TraceContext will be marked as new.
is_new(Boolean)(defaults to: nil)— Whether this trace context should be flagged
as newly created. Optional: if unset, will reflect whether a new
trace_id was generated when this object was created.
span_id(Integer)(defaults to: nil)— The context parent span ID as a 64-bit int.
If nil or omitted, the context will specify no parent span.
sampled(Boolean)(defaults to: nil)— Whether the context has decided to sample
this trace or not, or nil if the context does not specify a
sampling decision.
capture_stack(Boolean)(defaults to: false)— Whether the the context has decided to
capture stack traces. Ignored if sampled is not true.
Returns a string representation of this trace context, in the form<traceid>[/<spanid>][;o=<options>]. This form is suitable for
setting the trace context header.
Returns a string representation of this trace context, in the form<traceid>[/<spanid>][;o=<options>]. This form is suitable for
setting the trace context header.
Returns a new TraceContext instance that is identical to this instance
except for the given changes. All parameters are optional. See#initializefor more details on each parameter.
Parameters
trace_id(String)(defaults to: UNCHANGED)— New trace ID.
is_new(Boolean)(defaults to: UNCHANGED)— New setting for newness indicator.
span_id(Integer)(defaults to: UNCHANGED)— New parent span ID.
sampled(Boolean)(defaults to: UNCHANGED)— New sampling decision.
capture_stack(Boolean)(defaults to: UNCHANGED)— New stack capture decision.
[[["Easy to understand","easyToUnderstand","thumb-up"],["Solved my problem","solvedMyProblem","thumb-up"],["Other","otherUp","thumb-up"]],[["Hard to understand","hardToUnderstand","thumb-down"],["Incorrect information or sample code","incorrectInformationOrSampleCode","thumb-down"],["Missing the information/samples I need","missingTheInformationSamplesINeed","thumb-down"],["Other","otherDown","thumb-down"]],["Last updated 2025-09-04 UTC."],[],[],null,["# stackdriver-core - Class Stackdriver::Core::TraceContext (v1.7.0)\n\nVersion latestkeyboard_arrow_down\n\n- [1.7.0 (latest)](/ruby/docs/reference/stackdriver-core/latest/Stackdriver-Core-TraceContext)\n- [1.6.0](/ruby/docs/reference/stackdriver-core/1.6.0/Stackdriver-Core-TraceContext)\n- [1.5.0](/ruby/docs/reference/stackdriver-core/1.5.0/Stackdriver-Core-TraceContext) \nReference documentation and code samples for the stackdriver-core class Stackdriver::Core::TraceContext.\n\nA Stackdriver trace context links the current request into a performance\ntrace, and communicates tracing options between related requests. This\nfunctionality is used by the Stackdriver diagnostics libraries\n(including google-cloud-trace, google-cloud-logging, and other rubygems)\nthat integrate with the tracing service.\n\n\n\u003cbr /\u003e\n\nMost applications will not need to use the TraceContext class directly.\nThe Stackdriver libraries use it internally to store and propagate\ncontext information. \n\nInherits\n--------\n\n- Object\n\nMethods\n-------\n\n### .get\n\n def self.get() -\u003e TraceContext, nil\n\nReturns the current thread's trace context, or `nil` if no trace\ncontext has been set. \n**Returns**\n\n- ([TraceContext](./Stackdriver-Core-TraceContext), nil)\n**Example** \n\n```ruby\nrequire \"stackdriver/core\"\n\nctx = Stackdriver::Core::TraceContext.new\nStackdriver::Core::TraceContext.set ctx\nsame_ctx = Stackdriver::Core::TraceContext.get\n```\n\n### .parse_rack_env\n\n def self.parse_rack_env(env) -\u003e TraceContext\n\nObtains a TraceContext from the given Rack environment. This should\nbe used by any service that wants to obtain the TraceContext for a\nRack request. If a new trace context is generated in the process, it\nis memoized into the Rack environment so subsequent services will get\nthe same context.\n\n\nSpecifically, the following steps are attempted in order:\n\n1. Attempts to use any memoized context previously obtained.\n2. Attempts to parse the trace context header.\n3. Creates a new trace context with a random trace ID.\n\n\u003cbr /\u003e\n\nFurthermore, if a block is given, it is provided with an opportunity\nto modify the trace context. The current trace context and the Rack\nenvironment is passed to the block, and its result is used as the\nfinal trace context. The final context is memoized back into the\nRack environment. \n**Parameter**\n\n- **env** (Hash) --- The Rack environment hash \n**Returns**\n\n- ([TraceContext](./Stackdriver-Core-TraceContext))\n**Example** \n\n```ruby\nrequire \"stackdriver/core\"\n\nclass MyMiddleware\n def initialize app\n @app = app\n end\n\n def call env\n ctx = Stackdriver::Core::TraceContext.parse_rack_env env\n do_something_with ctx\n @app.call env\n end\nend\n```\n\n### .parse_string\n\n def self.parse_string(str) -\u003e TraceContext, nil\n\nAttempts to parse the given string as a trace context representation.\nExpects the form `\u003ctraceid\u003e[/\u003cspanid\u003e][;o=\u003coptions\u003e]`, which is the\nform used in the trace context header. Returns either the parsed\ntrace context, or `nil` if the string was malformed. \n**Parameter**\n\n- **str** (String) --- The string to parse. \n**Returns**\n\n- ([TraceContext](./Stackdriver-Core-TraceContext), nil)\n**Example** \n\n```ruby\nrequire \"stackdriver/core\"\n\nstr = \"0123456789abcdef0123456789abcdef/12345;o=1\"\nctx = Stackdriver::Core::TraceContext.parse_string str\n```\n\n### .set\n\n def self.set(trace_context) -\u003e TraceContext, nil\n\nSet the current thread's trace context, and returns the context. \n**Parameter**\n\n- **trace_context** ([TraceContext](./Stackdriver-Core-TraceContext), nil) --- The trace context to set for the current thread. May be `nil`. \n**Returns**\n\n- ([TraceContext](./Stackdriver-Core-TraceContext), nil) --- The context set.\n**Example** \n\n```ruby\nrequire \"stackdriver/core\"\n\nctx = Stackdriver::Core::TraceContext.new\nStackdriver::Core::TraceContext.set ctx\nsame_ctx = Stackdriver::Core::TraceContext.get\n```\n\n### #==\n\n def ==(other) -\u003e Boolean\n\n**Alias Of** : [#eql?](./Stackdriver-Core-TraceContext#Stackdriver__Core__TraceContext_eql?_instance_) \nStandard value equality check for this object. \n**Parameter**\n\n- **other** (Object) --- An object to compare with. \n**Returns**\n\n- (Boolean)\n\n### #capture_stack?\n\n def capture_stack?() -\u003e Boolean, nil\n\nReturns `true` if the context wants to capture stack traces, `false` if\nthe context does not, or `nil` if the context does not specify a\nsampling decision. \n**Returns**\n\n- (Boolean, nil)\n\n### #eql?\n\n def eql?(other) -\u003e Boolean\n\n**Aliases**\n\n- [#==](./Stackdriver-Core-TraceContext#Stackdriver__Core__TraceContext_==_instance_) \nStandard value equality check for this object. \n**Parameter**\n\n- **other** (Object) --- An object to compare with. \n**Returns**\n\n- (Boolean)\n\n### #hash\n\n def hash() -\u003e Integer\n\nGenerate standard hash code for this object. \n**Returns**\n\n- (Integer)\n\n### #initialize\n\n def initialize(trace_id: nil, is_new: nil, span_id: nil, sampled: nil, capture_stack: false) -\u003e TraceContext\n\nCreate a new TraceContext instance. \n**Parameters**\n\n- **trace_id** (String) *(defaults to: nil)* --- The trace ID as a hex string. If nil or omitted, a new random Trace ID will be generated, and this TraceContext will be marked as new.\n- **is_new** (Boolean) *(defaults to: nil)* --- Whether this trace context should be flagged as newly created. Optional: if unset, will reflect whether a new trace_id was generated when this object was created.\n- **span_id** (Integer) *(defaults to: nil)* --- The context parent span ID as a 64-bit int. If nil or omitted, the context will specify no parent span.\n- **sampled** (Boolean) *(defaults to: nil)* --- Whether the context has decided to sample this trace or not, or nil if the context does not specify a sampling decision.\n- **capture_stack** (Boolean) *(defaults to: false)* --- Whether the the context has decided to capture stack traces. Ignored if sampled is not true. \n**Returns**\n\n- ([TraceContext](./Stackdriver-Core-TraceContext)) --- a new instance of TraceContext\n**Example** \n\n```ruby\nrequire \"stackdriver/core\"\n\ntrace_id = \"0123456789abcdef0123456789abcdef\"\nctx = Stackdriver::Core::TraceContext.new trace_id: trace_id,\n sampled: true\n```\n\n### #new?\n\n def new?() -\u003e Boolean\n\nReturns `true` if this trace includes a newly generated trace_id. \n**Returns**\n\n- (Boolean)\n\n### #sampled?\n\n def sampled?() -\u003e Boolean, nil\n\nReturns `true` if the context wants to sample, `false` if the context\nwants explicitly to disable sampling, or `nil` if the context does\nnot specify. \n**Returns**\n\n- (Boolean, nil)\n\n### #span_id\n\n def span_id() -\u003e Integer, nil\n\nThe span ID, as a 64-bit integer, or `nil` if no span ID is present\nin the context. \n**Returns**\n\n- (Integer, nil)\n\n### #to_s\n\n def to_s() -\u003e String\n\n**Alias Of** : [#to_string](./Stackdriver-Core-TraceContext#Stackdriver__Core__TraceContext_to_string_instance_) \nReturns a string representation of this trace context, in the form\n`\u003ctraceid\u003e[/\u003cspanid\u003e][;o=\u003coptions\u003e]`. This form is suitable for\nsetting the trace context header. \n**Returns**\n\n- (String)\n\n### #to_string\n\n def to_string() -\u003e String\n\n**Aliases**\n\n- [#to_s](./Stackdriver-Core-TraceContext#Stackdriver__Core__TraceContext_to_s_instance_) \nReturns a string representation of this trace context, in the form\n`\u003ctraceid\u003e[/\u003cspanid\u003e][;o=\u003coptions\u003e]`. This form is suitable for\nsetting the trace context header. \n**Returns**\n\n- (String)\n\n### #trace_id\n\n def trace_id() -\u003e String\n\nThe trace ID, as a hex string. \n**Returns**\n\n- (String)\n\n### #with\n\n def with(trace_id: UNCHANGED, is_new: UNCHANGED, span_id: UNCHANGED, sampled: UNCHANGED, capture_stack: UNCHANGED) -\u003e TraceContext\n\nReturns a new TraceContext instance that is identical to this instance\nexcept for the given changes. All parameters are optional. See\n[#initialize](/ruby/docs/reference/stackdriver-core/latest/Stackdriver-Core-TraceContext#Stackdriver__Core__TraceContext_initialize_instance_ \"Stackdriver::Core::TraceContext#initialize (method)\") for more details on each parameter. \n**Parameters**\n\n- **trace_id** (String) *(defaults to: UNCHANGED)* --- New trace ID.\n- **is_new** (Boolean) *(defaults to: UNCHANGED)* --- New setting for newness indicator.\n- **span_id** (Integer) *(defaults to: UNCHANGED)* --- New parent span ID.\n- **sampled** (Boolean) *(defaults to: UNCHANGED)* --- New sampling decision.\n- **capture_stack** (Boolean) *(defaults to: UNCHANGED)* --- New stack capture decision. \n**Returns**\n\n- ([TraceContext](./Stackdriver-Core-TraceContext))\n**Example** \n\n```ruby\nrequire \"stackdriver/core\"\n\ntrace_id = \"0123456789abcdef0123456789abcdef\"\norig_ctx = Stackdriver::Core::TraceContext.new trace_id: trace_id,\n\nsampled_ctx = orig_ctx.with sampled: true\n```"]]
