From cfba04b38a0aa09cb994d044c0025646468b9508 Mon Sep 17 00:00:00 2001
From: Jaana Dogan <jbd@amazon.com>
Date: Tue, 2 Mar 2021 08:01:35 -0800
Subject: [PATCH] Clarify the cloud resource attributes (#1481)

---
 semantic_conventions/resource/cloud.yaml      | 19 ++++++++++++-------
 .../resource/semantic_conventions/cloud.md    |  8 ++++----
 2 files changed, 16 insertions(+), 11 deletions(-)

diff --git a/semantic_conventions/resource/cloud.yaml b/semantic_conventions/resource/cloud.yaml
index ad48f3ca9cf..3248fac0b50 100644
--- a/semantic_conventions/resource/cloud.yaml
+++ b/semantic_conventions/resource/cloud.yaml
@@ -23,20 +23,25 @@ groups:
       - id: account.id
         type: string
         brief: >
-          The cloud account ID used to identify different entities.
-        examples: ['opentelemetry']
+          The cloud account ID the resource is assigned to.
+        examples: ['111111111111', 'opentelemetry']
       - id: region
         type: string
         brief: >
-          A specific geographical location where different entities can run.
-        examples: ['us-central1']
+          The geographical region the resource is running. Refer to your
+          provider's docs to see the available regions, for example
+          [AWS regions](https://aws.amazon.com/about-aws/global-infrastructure/regions_az/), [Azure regions](https://azure.microsoft.com/en-us/global-infrastructure/geographies/), or
+          [Google Cloud regions](https://cloud.google.com/about/locations).
+        examples: ['us-central1', 'us-east-1']
       - id: zone
         type: string
         brief: >
-          Zones are a sub set of the region connected through low-latency links.
+          Cloud regions often have multiple, isolated locations known as zones
+          to increase availability. Zone represents the zone where the resource 
+          is running.
         note: >
-          In AWS, this is called availability-zone.
-        examples: ['us-central1-a']
+          AWS and Azure calls them availability zones or AZs.
+        examples: ['us-central1-a', 'us-east-1c']
       - id: infrastructure_service
         type:
           allow_custom_values: true
diff --git a/specification/resource/semantic_conventions/cloud.md b/specification/resource/semantic_conventions/cloud.md
index cdbd6c58271..55b25d17005 100644
--- a/specification/resource/semantic_conventions/cloud.md
+++ b/specification/resource/semantic_conventions/cloud.md
@@ -10,12 +10,12 @@
 | Attribute  | Type | Description  | Examples  | Required |
 |---|---|---|---|---|
 | `cloud.provider` | string | Name of the cloud provider. | `gcp` | No |
-| `cloud.account.id` | string | The cloud account ID used to identify different entities. | `opentelemetry` | No |
-| `cloud.region` | string | A specific geographical location where different entities can run. | `us-central1` | No |
-| `cloud.zone` | string | Zones are a sub set of the region connected through low-latency links. [1] | `us-central1-a` | No |
+| `cloud.account.id` | string | The cloud account ID the resource is assigned to. | `111111111111`; `opentelemetry` | No |
+| `cloud.region` | string | The geographical region the resource is running. Refer to your provider's docs to see the available regions, for example [AWS regions](https://aws.amazon.com/about-aws/global-infrastructure/regions_az/), [Azure regions](https://azure.microsoft.com/en-us/global-infrastructure/geographies/), or [Google Cloud regions](https://cloud.google.com/about/locations). | `us-central1`; `us-east-1` | No |
+| `cloud.zone` | string | Cloud regions often have multiple, isolated locations known as zones to increase availability. Zone represents the zone where the resource  is running. [1] | `us-central1-a`; `us-east-1c` | No |
 | `cloud.infrastructure_service` | string | The cloud infrastructure resource in use. [2] | `aws_ec2`; `azure_vm`; `gcp_compute_engine` | No |
 
-**[1]:** In AWS, this is called availability-zone.
+**[1]:** AWS and Azure calls them availability zones or AZs.
 
 **[2]:** The prefix of the service SHOULD match the one specified in `cloud.provider`.