-
Notifications
You must be signed in to change notification settings - Fork 6
Add development protobuf definition for process context #13
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Changes from all commits
9c3536d
e50806d
d239ca7
8c8b197
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
| 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). |
| 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; | ||
|
|
||
| // 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; | ||
|
Contributor
There was a problem hiding this comment. Choose a reason for hiding this commentThe 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?
Author
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. My current thinking/proposal for making this distinction is:
I only recently learned of the concept of baggage but I believe matches the semantics we should go for here. Perhaps we should rename
Author
There was a problem hiding this comment. Choose a reason for hiding this commentThe 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. | ||
| } | ||
There was a problem hiding this comment.
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?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
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_nameandservice_versionI believe are the ones that will commonly be blank.service_namehas well-defined fallback values,telemetry_sdk_*can be trivially hardcoded in every implementation andservice_instance_idcan be generated.There was a problem hiding this comment.
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