Skip to content

Latest commit

 

History

History
221 lines (156 loc) · 12.3 KB

semantic_conventions.md

File metadata and controls

221 lines (156 loc) · 12.3 KB
Raw

Semantic Conventions

Status: Mixed

This document defines the OpenTelemetry and Splunk specific standard attributes for Splunk distributions of OpenTelemetry instrumentation.

Note: No semantic conventions for data collection exist at this time.

OpenTelemetry Resource Attributes

Status: Stable

Description: Required and recommended OpenTelemetry resource semantic conventions.

All Splunk distributions of OpenTelemetry,

  • MUST set the following OpenTelemetry resource attributes according to the OpenTelemetry Semantic Conventions:

    • telemetry.sdk.name
    • telemetry.sdk.version
    • telemetry.sdk.language

  • SHOULD set the following resource attributes when applicable:

    • telemetry.auto.version

Note: this section does not apply to Real User Monitoring libraries, as they do not use the OpenTelemetry Resource.

Splunk Resource Attributes

Status: Stable

Description: Set of attributes used to uniquely identify a Splunk distro version in combination with OpenTelemetry's telemetry.sdk.* attributes.

Attribute Type Description Examples Required
splunk.distro.version string The version number of the Splunk distribution being used. 1.5.0 Yes

Note: this section does not apply to Real User Monitoring libraries, as they do not use the OpenTelemetry Resource.

Real User Monitoring Spans and Attributes

Status: Experimental

Real User Monitoring (RUM) libraries MUST set the service.name resource attribute to the value of the applicationName configuration property. This is the only resource attribute that RUM libraries are supposed to set because it's the only one the Zipkin exporter can understand.

The following attributes MUST be added to all spans produced by RUM libraries:

Name Type Description
app string The value of the applicationName property configured in SplunkRum; same as service.name resource attribute.
splunk.rumSessionId string The RUM session ID
splunk.rum.version string Version of the RUM library
component string Name of the instrumentation that produced this span

The following attributes MAY be added to all spans emitted by RUM libraries:

Name Type Description
deployment.environment string Value of the deploymentEnvironment property configured in SplunkRum, if any

Mobile RUM libraries (iOS, Android) MUST add device and system information to all spans:

Name Type Description
device.model.name string Name of the device
os.name string iOS or Android
os.version string Version of the OS

Web RUM library MUST add the following attributes to all spans:

Name Type Description
location.href string Value of location.href at the moment of creating the span.
splunk.script_instance string A 64bit identifier, unique to every instance of the SplunkRum library.

Profiling ResourceLogs Message

Status: Experimental

ResourceLogs is the upstream protobuf data type. It MUST be populated with the attributes from the OpenTelemetry resource.

InstrumentationLibraryLogs Message

Each ResourceLogs instance has an instance of InstrumenationLibraryLogs. For each InstrumentationLibraryLogs instance:

  • name - MUST be set to otel.profiling
  • version - MUST be set to 0.1.0

The resource field in ResourceLogs MUST contain the telemetry.sdk.language attribute.

LogRecord Message Common Attributes

Inside each InstrumentationLibraryLogs instance is a list of LogRecord instances. For each LogRecord instance:

  • com.splunk.sourcetype MUST be set to the value otel.profiling
  • profiling.data.type MUST be set to either allocation or cpu
  • profiling.data.format MUST be set to either text or pprof-gzip-base64

LogRecord Message text Data Format Specific Attributes

  • source.event.period MUST contain the sampling period in milliseconds if this LogRecord represents a periodic event
  • source.event.name OPTIONALLY can contain the name of the event that triggered the sampling
  • memory.allocated MUST contain the allocation size if this LogRecord represents a memory allocation event
  • thread.stack.truncated MUST be set to boolean true when this LogRecord does not contain the full stack trace

LogRecord Message Fields

  • Body MUST be populated with appropriate payload for specified data type and format.

LogRecord Message for text Data Format Specific Fields

  • Time MUST be set to the time that the call stack was sampled.
  • TraceId MUST be populated when a call stack has been sampled within a span scope.
  • SpanId MUST be populated when a call stack has been sampled within a span scope.

Call Stack Format for text Data Format

The call stack is a series of lines separated by newlines (\n). The first line of the call stack is a REQUIRED thread metadata line and the second line is a REQUIRED thread state line. The first two lines MAY be left empty, containing just the newlines.

An example metadata line is shown here:

"pool-1-thread-30" #49 prio=5 os_prio=31 cpu=0.12ms elapsed=8.50s tid=0x00007fde4d00c000 nid=0xba03 waiting on condition  [0x000070000ba40000]

The metadata line consists of several space separated fields:

  • thread name, surrounded with double quotes "
  • #<n> index of this thread
  • prio=<n> where <n> is the thread priority. 0 if not available.
  • os_prio=<n> where <n> is the operating system thread priority. 0 if not available.
  • cpu=<n><u> where <n> is the amount of cpu time consumed by the thread and <u> is a time unit abbreviation. 0 if not available.
  • elapsed=<n><u> where <n> is the wall time that thread has been alive and <u> is a time unit abbreviation. 0 if not available.
  • tid=0x<n> where <n> is the lowercase hexadecimal representation of the thread id. 0 if not available.
  • nid=0x<n> where <n> is the lowercase hexadecimal representation of the native thread id. 0 if not available.
  • The remainder of the line is a free-form text field that SHOULD indicate the status of the thread at the time the stack was captured (such as "running" or "waiting" )

If none of the fields in the thread metadata line are known, then the line MAY be blank/empty. That is, an empty thread metadata line indicates that no additional thread metadata is available for the stack trace.

Following the metadata line is a line containing the implementation specific thread state. For example, Java may provide:

  java.lang.Thread.State: TIMED_WAITING (sleeping)

The thread states for other runtimes are currently undefined.

The call stack details follow the thread state line. The call stack MUST have the top of the stack provided first and the bottom of the stack provided last. The format of each stack trace line is:

  at <function>(<file>:<lineno>)
  at <function>(<file>:<lineno>:<col>)
  • OPTIONAL leading whitespace (tabs or spaces)
  • OPTIONAL "at "
  • <function> - REQUIRED. Fully qualified name, i.e. containing the namespace, module and/or class name if applicable, of the function or method being invoked.
  • literal (
  • <file> - REQUIRED. The name of the source code file (including filename extension). If the function being executed is OS native, an implementation-specific indication SHOULD be used. If the source module cannot be determined (eg. when symbols have been excluded), the value MUST be unknown. The file MAY contain additional : characters.
  • literal : - REQUIRED.
  • <lineno> - REQUIRED. The line of source code that corresponds with the function invocation point. 0 if the line number is unknown.
  • literal : - REQUIRED if <col> is known, OPTIONAL otherwise.
  • <col> - OPTIONAL - If the runtime provides a column, it MAY be provided after the lineno, separated by :.
  • literal )

PPROF Profile.proto Data Format

Profile.proto is a data representation for profiling data. It is independent of the type of data being collected and the sampling process used to collect that data. The log message will contain a gzip-compressed, base64-encoded protocol buffer conforming to profile.proto. Each message contains either allocation or cpu samples determined by the data type specified for the log record. Data types int64 and string are protocol buffer types, consult protocol buffers documentation.

For each allocation and cpu sample:

  • label source.event.name of type string OPTIONALLY can contain the name of the event that triggered the sampling
  • label source.event.time of type int64 MUST be set to the unix time in millis when the sample was taken
  • label trace_id of type string MUST be set when sample was taken within a span scope
  • label span_id of type string MUST be set when sample was taken within a span scope
  • label thread.id of type int64 OPTIONALLY can be set to the thread identifier used by the runtime environment
  • label thread.name of type string OPTIONALLY can be set to the thread name used by the runtime environment
  • label thread.os.id of type int64 OPTIONALLY can be set to the thread identifier used by the operating system
  • label thread.stack.truncated of type string and with value true MUST be set when this sample does not contain the full stack trace

For each allocation sample:

  • value of type int64 must be set to allocation size in bytes

For each cpu sample:

  • label source.event.period of type int64 MUST contain the sampling period in milliseconds if this sample represents a periodic event
  • label thread.state of type string OPTIONALLY can be set to describe the state of the thread

Missing file name and function MUST be reported as unknown. Missing line number MUST be reported as -1.