From a159095c4e8469d35670594329e8fe74fd045094 Mon Sep 17 00:00:00 2001
From: Michael Safyan <michaelsafyan@google.com>
Date: Fri, 7 Jun 2024 14:46:09 -0500
Subject: [PATCH] Propose semantic conventions for GCP client library
 identification (#1047)

Co-authored-by: Liudmila Molkova <limolkova@microsoft.com>
---
 .chloggen/gcp-client-libraries.yaml        |  4 ++++
 docs/attributes-registry/gcp.md            | 19 +++++++++++++++++++
 model/registry/gcp.yaml                    | 20 ++++++++++++++++++++
 model/trace/instrumentation/gcp-client.yml | 12 ++++++++++++
 4 files changed, 55 insertions(+)
 create mode 100755 .chloggen/gcp-client-libraries.yaml
 create mode 100644 model/trace/instrumentation/gcp-client.yml

diff --git a/.chloggen/gcp-client-libraries.yaml b/.chloggen/gcp-client-libraries.yaml
new file mode 100755
index 000000000..0ae23ba74
--- /dev/null
+++ b/.chloggen/gcp-client-libraries.yaml
@@ -0,0 +1,4 @@
+change_type: 'enhancement'
+component: gcp
+note: Introduces `gcp.client.service` scope attribute.
+issues: [ 1047 ]
diff --git a/docs/attributes-registry/gcp.md b/docs/attributes-registry/gcp.md
index 0a8ba6319..cade70315 100644
--- a/docs/attributes-registry/gcp.md
+++ b/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 the Google Cloud service for which the official client library is intended. [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'.
+
 ## GCP Cloud Run Attributes
 
 This document defines attributes for Google Cloud Run.
diff --git a/model/registry/gcp.yaml b/model/registry/gcp.yaml
index 3b00f7040..307713df8 100644
--- a/model/registry/gcp.yaml
+++ b/model/registry/gcp.yaml
@@ -1,4 +1,24 @@
 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 the Google Cloud service for which the official client library is intended.
+        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'.
+        examples: ['appengine', 'run', 'firestore', 'alloydb', 'spanner']
   - id: registry.gcp.cloud_run
     prefix: gcp.cloud_run
     type: attribute_group
diff --git a/model/trace/instrumentation/gcp-client.yml b/model/trace/instrumentation/gcp-client.yml
new file mode 100644
index 000000000..08a6ac311
--- /dev/null
+++ b/model/trace/instrumentation/gcp-client.yml
@@ -0,0 +1,12 @@
+groups:
+- id: gcp.client.attributes
+  type: attribute_group
+  brief: Conventions for official Google Cloud client libraries.
+  prefix: gcp.client
+  stability: experimental
+  attributes:
+  - ref: gcp.client.service
+    requirement_level:
+      conditionally_required:
+        Required if and only if the instrumentation library is an official,
+        Google-provided GCP and/or Firebase client library.