Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 5 additions & 0 deletions process-context/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
# OpenTelemetry Process Context (Under development)

This folder currently contains the development protobuf definitions for the specification proposed in https://docs.google.com/document/d/1-4jo29vWBZZ0nKKAOG13uAQjRcARwmRc4P313LTbPOE/edit?tab=t.0 .

The `OtelProcessCtx` message is used to allow in-process libraries (such as the OTel SDKs running inside an application) to share information with outside readers (such as the OpenTelemetry eBPF Profiler).
40 changes: 40 additions & 0 deletions process-context/otel_process_ctx.proto
Original file line number Diff line number Diff line change
@@ -0,0 +1,40 @@
syntax = "proto3";

package otel_process_ctx.v1development;

message OtelProcessCtx {
// Additional key/value pairs as resources https://opentelemetry.io/docs/specs/otel/resource/sdk/
// Similar to baggage https://opentelemetry.io/docs/concepts/signals/baggage/ / https://opentelemetry.io/docs/specs/otel/overview/#baggage-signal
//
// Providing resources is optional.
//
// If a key in this field would match one of the attributes already defined as a first-class field below (e.g. `service.name`),
// the first-class field must always take priority.
// Readers MAY choose to fallback to a value in `resources` if its corresponding first-class field is empty, or they CAN ignore it.
map<string, string> resources = 1;

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What happens if this field conflicts with the hard-coded conventions you have?

Also what happens if any of the conventions in the below proto are empty?

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What happens if this field conflicts with the hard-coded conventions you have?

Good question! We propose that hard-coded conventions always take priority. Readers can choose to fallback to a value in a resources field if the hard-coded field is empty, or can ignore it.

Also what happens if any of the conventions in the below proto are empty?

Our proposal on this (from the spec doc) is

"The reference implementation strongly recommends that callers provide the following keys (from the existing semantic conventions), but they can be empty if needed"

In particular deployment_environment_name and service_version I believe are the ones that will commonly be blank. service_name has well-defined fallback values, telemetry_sdk_* can be trivially hardcoded in every implementation and service_instance_id can be generated.

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Added a comment about this in e50806d


// We strongly recommend that the following first-class fields are provided, but they can be empty if needed.
// In particular for `deployment_environment_name` and `service_version` often need to be configured for a given application
// and cannot be inferred. For the others, see the semantic conventions documentation for recommended ways of setting them.

// https://opentelemetry.io/docs/specs/semconv/registry/attributes/deployment/#deployment-environment-name
string deployment_environment_name = 2;
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

My concern here is that there is no documentation or guideline about where resource attributes should end up (map<> vs dedicated field). What promotes dedicated attributes to have a dedicated field in the proto?

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

My current thinking/proposal for making this distinction is:

  • Dedicated field => Standardized attributes that most apps are expected to fill, with semantics matching existing semantic conventions

  • Resources => Free-form payload that can be used to pass along data. E.g. from https://opentelemetry.io/docs/concepts/signals/baggage/ :

    Baggage is contextual information that resides next to context. Baggage is a key-value store, which means it lets you propagate any data you like alongside context.

    Baggage means you can pass data across services and processes, making it available to add to traces, metrics, or logs in those services.

    and from https://opentelemetry.io/docs/specs/otel/overview/#baggage-signal :

    While Baggage can be used to prototype other cross-cutting concerns, this mechanism is primarily intended to convey values for the OpenTelemetry observability systems.

    These values can be consumed from Baggage and used as additional attributes for metrics, or additional context for logs and traces.

I only recently learned of the concept of baggage but I believe matches the semantics we should go for here. Perhaps we should rename resources => baggage to be more explicit even?

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Added a comment about this in d239ca7

// https://opentelemetry.io/docs/specs/semconv/registry/attributes/service/#service-instance-id
string service_instance_id = 3;
// https://opentelemetry.io/docs/specs/semconv/registry/attributes/service/#service-name
string service_name = 4;
// https://opentelemetry.io/docs/specs/semconv/registry/attributes/service/#service-version
string service_version = 5;
// https://opentelemetry.io/docs/specs/semconv/registry/attributes/telemetry/#telemetry-sdk-language
string telemetry_sdk_language = 6;
// https://opentelemetry.io/docs/specs/semconv/registry/attributes/telemetry/#telemetry-sdk-version
string telemetry_sdk_version = 7;
// https://opentelemetry.io/docs/specs/semconv/registry/attributes/telemetry/#telemetry-sdk-name
string telemetry_sdk_name = 8;

// New first-class fields should be added only if:
// * Providing them is strongly recommended
// * They match a new or existing OTEL semantic convention
//
// Otherwise, `resources` should be used instead.
}