Propose semantic conventions for GCP client library identification

.chloggen/gcp-client-libraries.yaml

@@ -0,0 +1,4 @@
+change_type: 'enhancement'
+component: instrumentation, gcp
+note: Introduced `gcp.client.service` and 'instrumentation.source.*' attributes.
+issues: [ 1047 ]

docs/attributes-registry/README.md

@@ -60,6 +60,7 @@ Currently, the following namespaces exist:
 - [Heroku](heroku.md)
 - [Host](host.md)
 - [HTTP](http.md)
+- [Instrumentation](instrumentation.md)
 - [iOS](ios.md)
 - [JVM](jvm.md)
 - [K8s](k8s.md)

docs/attributes-registry/gcp.md

@@ -6,9 +6,28 @@
 
 # GCP
 
+- [Gcp](#gcp-attributes)
+- [Gcp Client](#gcp-client-attributes)
 - [Gcp Cloud Run](#gcp-cloud-run-attributes)
 - [Gcp Gce](#gcp-gce-attributes)
 
+## GCP Attributes
+
+Attributes for Google Cloud
+
+| Attribute | Type | Description | Examples | Stability |
+| --------- | ---- | ----------- | -------- | --------- |
+
+## GCP Client Attributes
+
+Attributes for Google Cloud client libraries.
+
+| Attribute            | Type   | Description                                            | Examples                                              | Stability                                                        |
+| -------------------- | ------ | ------------------------------------------------------ | ----------------------------------------------------- | ---------------------------------------------------------------- |
+| `gcp.client.service` | string | Identifies official Google Cloud client libraries. [1] | `appengine`; `run`; `firestore`; `alloydb`; `spanner` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
+
+**[1]:** Intended to be a stable identifier for Google Cloud client libraries that is uniform across implementation languages. The value should be derived from the canonical service domain for the service; for example, 'foo.googleapis.com' should result in a value of 'foo'. This attribute should be accompanied by 'instrumentation.source.repo' and/or 'instrumentation.source.target' when the combination of 'gcp.client.service' and 'telemetry.sdk.language' is insufficient to uniquely identify the particular client library.
+
 ## GCP Cloud Run Attributes
 
 This document defines attributes for Google Cloud Run.

docs/attributes-registry/instrumentation.md

@@ -0,0 +1,18 @@
+<!--- Hugo front matter used to generate the website version of this page:
+--->
+
+<!-- NOTE: THIS FILE IS AUTOGENERATED. DO NOT EDIT BY HAND. -->
+<!-- see templates/registry/markdown/attribute_namespace.md.j2 -->
+
+# Instrumentation
+
+## Instrumentation Attributes
+
+Describes properties about the library that is being instrumented or that is responsible for performing the instrumentation.
+
+| Attribute                       | Type   | Description                                                    | Examples                                                 | Stability                                                        |
+| ------------------------------- | ------ | -------------------------------------------------------------- | -------------------------------------------------------- | ---------------------------------------------------------------- |
+| `instrumentation.source.repo`   | string | The repository associated with the InstrumentationScope.       | `github.com/organization/repo`; `gitlab.com/group/repo`  | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
+| `instrumentation.source.target` | string | The build target associated with the InstrumentationScope. [1] | `//in/bazel/path/to/my/folder:target`; `inGradleYourLib` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
+
+**[1]:** Particularly useful if the InstrumentationScope library cannot be triangulated from the name and `instrumenation.source.repo` alone. If multiple build targets produce the same result, choose the narrowest possible target (e.g. for Make: "mylib" rather than "all"; for Bazel: "//path/to/specific:target", not "//path/..."; etc.).

model/registry/gcp.yaml

@@ -1,4 +1,28 @@
 groups:
+  - id: registry.gcp
+    prefix: gcp
+    type: attribute_group
+    brief: Attributes for Google Cloud
+  - id: registry.gcp.client
+    prefix: gcp.client
+    type: attribute_group
+    brief: >
+      Attributes for Google Cloud client libraries.
+    attributes:
+      - id: service
+        type: string
+        stability: experimental
+        brief: Identifies official Google Cloud client libraries.
+        note: >
+          Intended to be a stable identifier for Google Cloud client libraries
+          that is uniform across implementation languages. The value should be
+          derived from the canonical service domain for the service; for
+          example, 'foo.googleapis.com' should result in a value of 'foo'.
+          This attribute should be accompanied by 'instrumentation.source.repo'
+          and/or 'instrumentation.source.target' when the combination of
+          'gcp.client.service' and 'telemetry.sdk.language' is insufficient
+          to uniquely identify the particular client library.
+        examples: ['appengine', 'run', 'firestore', 'alloydb', 'spanner']
   - id: registry.gcp.cloud_run
     prefix: gcp.cloud_run
     type: attribute_group

model/registry/instrumentation.yaml

@@ -0,0 +1,24 @@
+groups:
+- id: registry.instrumentation
+  prefix: instrumentation
+  type: attribute_group
+  brief: >
+    Describes properties about the library that is being instrumented or that
+    is responsible for performing the instrumentation.
+  attributes:
+    - id: source.repo
+      type: string
+      stability: experimental
+      brief: The repository associated with the InstrumentationScope.
+      examples: [github.com/organization/repo, gitlab.com/group/repo]
+    - id: source.target
+      type: string
+      stability: experimental
+      brief: The build target associated with the InstrumentationScope.
+      examples: ['//in/bazel/path/to/my/folder:target', 'inGradleYourLib']
+      note: >
+        Particularly useful if the InstrumentationScope library cannot be
+        triangulated from the name and `instrumenation.source.repo` alone.
+        If multiple build targets produce the same result, choose the
+        narrowest possible target (e.g. for Make: "mylib" rather than "all";
+        for Bazel: "//path/to/specific:target", not "//path/..."; etc.).

model/trace/instrumentation/gcp-client.yml

@@ -0,0 +1,9 @@
+groups:
+- id: gcp.client.scope
+  type: scope
+  brief: Conventions for official Google Cloud client libraries.
+  prefix: gcp.client
+  stability: experimental
+  attributes:
+  - ref: gcp.client.service
+    requirement_level: opt_in

model/trace/instrumentation/instrumentation.yml

@@ -0,0 +1,13 @@
+groups:
+- id: instrumentation.scope
+  type: scope
+  brief: >
+    The `instrumentation` conventions are intended to provide common
+    mechanisms for triangulating and identifying instrumentation libraries.
+  prefix: instrumentation
+  stability: experimental
+  attributes:
+  - ref: instrumentation.source.repo
+    requirement_level: opt_in
+  - ref: instrumentation.source.target
+    requirement_level: opt_in