Reference documentation and code samples for the Cloud Trace API module Google::Cloud::Trace.
Stackdriver Trace
The Stackdriver Trace service collects and stores latency data from your
application and displays it in the Google Cloud Platform Console, giving
you detailed near-real-time insight into application performance.
Configure the Stackdriver Trace instrumentation Middleware.
The following Stackdriver Trace configuration parameters are
supported:
project_id - (String) Project identifier for the Stackdriver
Trace service you are connecting to. (The parameter project is
considered deprecated, but may also be used.)
credentials - (String, Hash, Google::Auth::Credentials) The path to
the keyfile as a String, the contents of the keyfile as a Hash, or a
Google::Auth::Credentials object. (See Credentials) (The
parameter keyfile is considered deprecated, but may also be used.)
scope - (String, Array
timeout - (Integer) Default timeout to use in requests.
endpoint - (String) Override of the endpoint host name, or nil
to use the default endpoint.
capture_stack - (Boolean) Whether to capture stack traces for each
span. Default: false
sampler - (Proc) A sampler Proc makes the decision whether to record
a trace for each request. Default: Google::Cloud::Trace::TimeSampler
span_id_generator - (Proc) A generator Proc that generates the name
String for new TraceRecord. Default: random numbers
notifications - (Array) An array of ActiveSupport notification types
to include in traces. Rails-only option. Default:
Google::Cloud::Trace::Railtie::DEFAULT_NOTIFICATIONS
max_data_length - (Integer) The maximum length of span properties
recorded with ActiveSupport notification events. Rails-only option.
Default:
Google::Cloud::Trace::Notifications::DEFAULT_MAX_DATA_LENGTH
on_error - (Proc) A Proc to be run when an error is encountered
during the reporting of traces by the middleware. The Proc must take
the error object as the single argument.
Open a new span for the current thread, instrumenting the given block.
The span is created within the current thread's trace context as set by
Trace.set. The context is updated so any further calls
within the block will create subspans. The new span is also yielded to
the block.
Does nothing if there is no trace context for the current thread.
Parameters
name (String) — Name of the span to create
kind (Google::Cloud::Trace::SpanKind) (defaults to: Google::Cloud::Trace::SpanKind::UNSPECIFIED) — Kind of span to create.
Optional.
labels (Hash{String => String}) (defaults to: {}) — Labels for the span
Example
require"google/cloud/trace"trace_client=Google::Cloud::Trace.newtrace=trace_client.new_traceGoogle::Cloud::Trace.settraceGoogle::Cloud::Trace.in_span"my_span"do|span|span.labels["foo"]="bar"# Do stuff...Google::Cloud::Trace.in_span"my_subspan"do|subspan|subspan.labels["foo"]="sub-bar"# Do other stuff...endend
Creates a new object for connecting to the Stackdriver Trace service.
Each call creates a new connection.
For more information on connecting to Google Cloud see the
Authentication Guide.
Parameters
project_id (String) (defaults to: nil) — Project identifier for the Stackdriver Trace
service you are connecting to. If not present, the default project for
the credentials is used.
credentials (String, Hash, Google::Auth::Credentials) (defaults to: nil) — The path to
the keyfile as a String, the contents of the keyfile as a Hash, or a
Google::Auth::Credentials object. (See Credentials)
scope (String, Array<String>) (defaults to: nil) —
Set the current trace span being measured for the current thread, or
the current trace if no span is currently open. This may be used with
web frameworks that assign a thread to each request, to track the
trace instrumentation state for the request being handled. You may use
Trace.get to retrieve the data.
Parameter
trace (Google::Cloud::Trace::TraceSpan, Google::Cloud::Trace::TraceRecord, nil) — The current span
being measured, the current trace object, or nil if none.
[[["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,["# Cloud Trace API - Module Google::Cloud::Trace (v0.45.0)\n\nVersion latestkeyboard_arrow_down\n\n- [0.45.0 (latest)](/ruby/docs/reference/google-cloud-trace/latest/Google-Cloud-Trace)\n- [0.44.1](/ruby/docs/reference/google-cloud-trace/0.44.1/Google-Cloud-Trace)\n- [0.43.0](/ruby/docs/reference/google-cloud-trace/0.43.0/Google-Cloud-Trace)\n- [0.42.2](/ruby/docs/reference/google-cloud-trace/0.42.2/Google-Cloud-Trace)\n- [0.41.4](/ruby/docs/reference/google-cloud-trace/0.41.4/Google-Cloud-Trace) \nReference documentation and code samples for the Cloud Trace API module Google::Cloud::Trace.\n\nStackdriver Trace\n-----------------\n\nThe Stackdriver Trace service collects and stores latency data from your\napplication and displays it in the Google Cloud Platform Console, giving\nyou detailed near-real-time insight into application performance.\n\nSee [Stackdriver Trace Overview](./index.html \"Stackdriver Trace Overview\").\n\nMethods\n-------\n\n### .configure\n\n def self.configure() -\u003e Google::Cloud::Config\n\nConfigure the Stackdriver Trace instrumentation Middleware.\n\n\nThe following Stackdriver Trace configuration parameters are\nsupported:\n\n- `project_id` - (String) Project identifier for the Stackdriver Trace service you are connecting to. (The parameter `project` is considered deprecated, but may also be used.)\n- `credentials` - (String, Hash, Google::Auth::Credentials) The path to the keyfile as a String, the contents of the keyfile as a Hash, or a Google::Auth::Credentials object. (See [Credentials](/ruby/docs/reference/google-cloud-trace/latest/Google-Cloud-Trace-Credentials \"Google::Cloud::Trace::Credentials (class)\")) (The parameter `keyfile` is considered deprecated, but may also be used.)\n- `scope` - (String, Array\n- `timeout` - (Integer) Default timeout to use in requests.\n- `endpoint` - (String) Override of the endpoint host name, or `nil` to use the default endpoint.\n- `capture_stack` - (Boolean) Whether to capture stack traces for each span. Default: `false`\n- `sampler` - (Proc) A sampler Proc makes the decision whether to record a trace for each request. Default: `Google::Cloud::Trace::TimeSampler`\n- `span_id_generator` - (Proc) A generator Proc that generates the name String for new TraceRecord. Default: `random numbers`\n- `notifications` - (Array) An array of ActiveSupport notification types to include in traces. Rails-only option. Default: `Google::Cloud::Trace::Railtie::DEFAULT_NOTIFICATIONS`\n- `max_data_length` - (Integer) The maximum length of span properties recorded with ActiveSupport notification events. Rails-only option. Default: `Google::Cloud::Trace::Notifications::DEFAULT_MAX_DATA_LENGTH`\n- `on_error` - (Proc) A Proc to be run when an error is encountered during the reporting of traces by the middleware. The Proc must take the error object as the single argument.\n\n\u003cbr /\u003e\n\nSee the [Configuration Guide](./INSTRUMENTATION \"Configuration Guide\") for full\nconfiguration parameters. \n**Yields**\n\n- (Google::Cloud.configure.trace) \n**Returns**\n\n- (Google::Cloud::Config) --- The configuration object the Google::Cloud::Trace module uses.\n\n### .get\n\n def self.get() -\u003e Google::Cloud::Trace::TraceSpan, Google::Cloud::Trace::TraceRecord, nil\n\nRetrieve the current trace span or trace object for the current thread.\nThis data should previously have been set using\n[Trace.set](/ruby/docs/reference/google-cloud-trace/latest/Google-Cloud-Trace#Google__Cloud__Trace_set_class_ \"Google::Cloud::Trace.set (method)\"). \n**Returns**\n\n- (Google::Cloud::Trace::TraceSpan, [Google::Cloud::Trace::TraceRecord](./Google-Cloud-Trace-TraceRecord), nil) --- The span or trace object, or `nil`.\n**Example** \n\n```ruby\nrequire \"google/cloud/trace\"\n\ntrace_client = Google::Cloud::Trace.new\ntrace = trace_client.new_trace\nGoogle::Cloud::Trace.set trace\n\n# Later...\nGoogle::Cloud::Trace.get.create_span \"my_span\"\n```\n\n### .in_span\n\n def self.in_span(name, kind: Google::Cloud::Trace::SpanKind::UNSPECIFIED, labels: {})\n\nOpen a new span for the current thread, instrumenting the given block.\nThe span is created within the current thread's trace context as set by\n[Trace.set](/ruby/docs/reference/google-cloud-trace/latest/Google-Cloud-Trace#Google__Cloud__Trace_set_class_ \"Google::Cloud::Trace.set (method)\"). The context is updated so any further calls\nwithin the block will create subspans. The new span is also yielded to\nthe block.\n\n\n\u003cbr /\u003e\n\nDoes nothing if there is no trace context for the current thread. \n**Parameters**\n\n- **name** (String) --- Name of the span to create\n- **kind** ([Google::Cloud::Trace::SpanKind](./Google-Cloud-Trace-SpanKind)) *(defaults to: Google::Cloud::Trace::SpanKind::UNSPECIFIED)* --- Kind of span to create. Optional.\n- **labels** (Hash{String =\\\u003e String}) *(defaults to: {})* --- Labels for the span\n**Example** \n\n```ruby\nrequire \"google/cloud/trace\"\n\ntrace_client = Google::Cloud::Trace.new\ntrace = trace_client.new_trace\nGoogle::Cloud::Trace.set trace\n\nGoogle::Cloud::Trace.in_span \"my_span\" do |span|\n span.labels[\"foo\"] = \"bar\"\n # Do stuff...\n\n Google::Cloud::Trace.in_span \"my_subspan\" do |subspan|\n subspan.labels[\"foo\"] = \"sub-bar\"\n # Do other stuff...\n end\nend\n```\n\n### .new\n\n def self.new(project_id: nil, credentials: nil, scope: nil, timeout: nil, endpoint: nil, project: nil, keyfile: nil) -\u003e Google::Cloud::Trace::Project\n\nCreates a new object for connecting to the Stackdriver Trace service.\nEach call creates a new connection.\n\n\n\u003cbr /\u003e\n\nFor more information on connecting to Google Cloud see the\n[Authentication Guide](./AUTHENTICATION \"Authentication Guide\"). \n**Parameters**\n\n- **project_id** (String) *(defaults to: nil)* --- Project identifier for the Stackdriver Trace service you are connecting to. If not present, the default project for the credentials is used.\n- **credentials** (String, Hash, Google::Auth::Credentials) *(defaults to: nil)* --- The path to the keyfile as a String, the contents of the keyfile as a Hash, or a Google::Auth::Credentials object. (See [Credentials](/ruby/docs/reference/google-cloud-trace/latest/Google-Cloud-Trace-Credentials \"Google::Cloud::Trace::Credentials (class)\"))\n- **scope** (String, Array\\\u003cString\\\u003e) *(defaults to: nil)* ---\n\n The OAuth 2.0 scopes controlling\n the set of resources and operations that the connection can access.\n See [Using OAuth 2.0 to Access Google\n APIs](https://developers.google.com/identity/protocols/OAuth2).\n\n The default scope is:\n - `https://www.googleapis.com/auth/cloud-platform`\n- **timeout** (Integer) *(defaults to: nil)* --- Default timeout to use in requests. Optional.\n- **endpoint** (String) *(defaults to: nil)* --- Override of the endpoint host name. Optional. If the param is nil, uses the default endpoint.\n- **project** (String) *(defaults to: nil)* --- Alias for the `project_id` argument. Deprecated.\n- **keyfile** (String) *(defaults to: nil)* --- Alias for the `credentials` argument. Deprecated. \n**Returns**\n\n- ([Google::Cloud::Trace::Project](./Google-Cloud-Trace-Project)) \n**Raises**\n\n- (ArgumentError)\n**Example** \n\n```ruby\nrequire \"google/cloud/trace\"\n\ntrace_client = Google::Cloud::Trace.new\n\ntraces = trace_client.list_traces Time.now - 3600, Time.now\ntraces.each do |trace|\n puts \"Retrieved trace ID: #{trace.trace_id}\"\nend\n```\n\n### .set\n\n def self.set(trace)\n\nSet the current trace span being measured for the current thread, or\nthe current trace if no span is currently open. This may be used with\nweb frameworks that assign a thread to each request, to track the\ntrace instrumentation state for the request being handled. You may use\n[Trace.get](/ruby/docs/reference/google-cloud-trace/latest/Google-Cloud-Trace#Google__Cloud__Trace_get_class_ \"Google::Cloud::Trace.get (method)\") to retrieve the data. \n**Parameter**\n\n- **trace** (Google::Cloud::Trace::TraceSpan, [Google::Cloud::Trace::TraceRecord](./Google-Cloud-Trace-TraceRecord), nil) --- The current span being measured, the current trace object, or `nil` if none.\n**Example** \n\n```ruby\nrequire \"google/cloud/trace\"\n\ntrace_client = Google::Cloud::Trace.new\ntrace = trace_client.new_trace\nGoogle::Cloud::Trace.set trace\n\n# Later...\nGoogle::Cloud::Trace.get.create_span \"my_span\"\n```\n\nConstants\n---------\n\n### THREAD_KEY\n\n**value:** :**stackdriver_trace_span**\n\n### VERSION\n\n**value:**\"0.45.0\".freeze"]]
