New: Event payload Cloud Resource Context (#825)

* First version of cloud resource context spec

Author: antonpirker

develop-docs/sdk/event-payloads/contexts.mdx

@@ -38,8 +38,8 @@ The `type` and default key is `"device"`.
 `family`
 
 : _Optional_. The family of the device. This is usually the common part of model
-  names across generations. For instance, `iPhone` would be a reasonable family,
-  so would be `Samsung Galaxy`.
+names across generations. For instance, `iPhone` would be a reasonable family,
+so would be `Samsung Galaxy`.
 
 `model`
 
@@ -56,12 +56,12 @@ The `type` and default key is `"device"`.
 `battery_level`
 
 : _Optional_. If the device has a battery, this can be a floating point value
-  defining the battery level (in the range 0-100).
+defining the battery level (in the range 0-100).
 
 `orientation`
 
 : _Optional_. This can be a string `portrait` or `landscape` to define the
-  orientation of a device.
+orientation of a device.
 
 `manufacturer`
 
@@ -106,7 +106,7 @@ The `type` and default key is `"device"`.
 `simulator`
 
 : _Optional_. A flag indicating whether this device is a simulator or an actual
-  device.
+device.
 
 `memory_size`
 
@@ -131,17 +131,17 @@ The `type` and default key is `"device"`.
 `external_storage_size`
 
 : _Optional_. Total size of an attached external storage in bytes (for example,
-  android SDK card).
+android SDK card).
 
 `external_free_storage`
 
 : _Optional_. Free size of an attached external storage in bytes (for example,
-  android SDK card).
+android SDK card).
 
 `boot_time`
 
 : _Optional_. A formatted UTC timestamp when the system was booted. For example,
-  `"2018-02-08T12:52:12Z"`.
+`"2018-02-08T12:52:12Z"`.
 
 `timezone`
 
@@ -161,8 +161,8 @@ The `type` and default key is `"device"`.
 
 `processor_frequency`
 
-: _Optional_. Processor frequency in MHz. Note that the actual CPU frequency might vary depending on current load and power conditions, 
-  especially on low-powered devices like phones and laptops.
+: _Optional_. Processor frequency in MHz. Note that the actual CPU frequency might vary depending on current load and power conditions,
+especially on low-powered devices like phones and laptops.
 
 `device_type`
 
@@ -205,15 +205,15 @@ The `type` and default key is `"os"`. However, since contexts can be set
 multiple times under different keys, there has historically been a lot of
 confusion about which OS context represents what. So here's some examples:
 
-* In events reported from a Python/ASP.NET/Rails web backend, the OS context
+- In events reported from a Python/ASP.NET/Rails web backend, the OS context
   under the default key `"os"` is the server's operating system, and is set by
   the SDK (if at all).
 
   Additionally, the Sentry server will attempt to parse the `User-Agent` header
   from the event's [Request Interface](/sdk/event-payloads/request/) and create a _secondary_ OS
   context under the non-default key `"client_os"`.
 
-* In events reported from a JS web frontend, the SDK typically reports no OS
+- In events reported from a JS web frontend, the SDK typically reports no OS
   context.
 
   The server however knows by looking at the platform (`"javascript"`) that the
@@ -222,11 +222,11 @@ confusion about which OS context represents what. So here's some examples:
 
 To summarize:
 
-* `"os"` key for the device generating the event.
-* `"client_os"` key for an adjacent client device's OS (that is _not_ the
+- `"os"` key for the device generating the event.
+- `"client_os"` key for an adjacent client device's OS (that is _not_ the
   device creating the event) if it's important. The Sentry server sets this as part of
   User-Agent parsing, but SDKs can set this directly too.
-* If in doubt, just send `"os"`. Any other keys are not searchable in the
+- If in doubt, just send `"os"`. Any other keys are not searchable in the
   product and will not be visually pronounced using icons, so using something
   like `"server_os"` to clarify what you meant is probably going to
   backfire with regards to the overall product experience.
@@ -252,7 +252,7 @@ To summarize:
 `kernel_version`
 
 : _Optional_. An independent kernel version string. This is typically the entire
-  output of the `uname` syscall.
+output of the `uname` syscall.
 
 `rooted`
 
@@ -265,10 +265,10 @@ To summarize:
 `raw_description`
 
 : _Optional_. An unprocessed description string obtained by the operating
-  system. For some well-known runtimes, Sentry will attempt to parse `name` and
-  `version` from this string, if they are not explicitly given.
+system. For some well-known runtimes, Sentry will attempt to parse `name` and
+`version` from this string, if they are not explicitly given.
 
-### Example
+### Example OS Context
 
 The OS Context for the 3 major OSs should look like this:
 
@@ -278,7 +278,7 @@ The OS Context for the 3 major OSs should look like this:
     "type": "os",
     "name": "Windows",
     "version": "10.0.19041",
-    "build": "662",
+    "build": "662"
   },
   "mac": {
     "type": "os",
@@ -296,7 +296,6 @@ The OS Context for the 3 major OSs should look like this:
 }
 ```
 
-
 ## Runtime Context
 
 Runtime context describes a runtime in more detail. Typically, this context is
@@ -316,8 +315,8 @@ The `type` and default key is `"runtime"`.
 `raw_description`
 
 : _Optional_. An unprocessed description string obtained by the runtime. For
-  some well-known runtimes, Sentry will attempt to parse `name` and `version`
-  from this string, if they are not explicitly given.
+some well-known runtimes, Sentry will attempt to parse `name` and `version`
+from this string, if they are not explicitly given.
 
 ## App Context
 
@@ -342,7 +341,7 @@ The `type` and default key is `"app"`.
 `app_identifier`
 
 : _Optional_. Version-independent application identifier, often a dotted bundle
-  ID.
+ID.
 
 `app_name`
 
@@ -412,7 +411,7 @@ GPU context describes the GPU of the device.
 
 : _Optional_. The device low-level API type.
 
-  Examples: `"Apple Metal"` or `"Direct3D11"`
+Examples: `"Apple Metal"` or `"Direct3D11"`
 
 `multi_threaded_rendering`
 
@@ -424,11 +423,11 @@ GPU context describes the GPU of the device.
 
 `max_texture_size`
 
-: _Optional_. Largest size of a texture that is supported by the graphics hardware. For  example, `16384`.
+: _Optional_. Largest size of a texture that is supported by the graphics hardware. For example, `16384`.
 
 `graphics_shader_level`
 
-: _Optional_. Approximate "shader capability" level of the graphics device. For  example, `Shader Model 2.0, OpenGL ES 3.0, Metal / OpenGL ES 3.1, 27 (unknown)`.
+: _Optional_. Approximate "shader capability" level of the graphics device. For example, `Shader Model 2.0, OpenGL ES 3.0, Metal / OpenGL ES 3.1, 27 (unknown)`.
 
 `supports_draw_call_instancing`
 
@@ -446,17 +445,21 @@ GPU context describes the GPU of the device.
 
 : _Optional_. Are geometry shaders available on the device?
 
-Example:
+### Example GPU Context
 
 ```json
-"gpu": {
-  "name": "AMD Radeon Pro 560",
-  "vendor_name": "Apple",
-  "memory_size": 4096,
-  "api_type": "Metal",
-  "multi_threaded_rendering": true,
-  "version": "Metal",
-  "npot_support": "Full"
+{
+  "contexts": {
+    "gpu": {
+      "name": "AMD Radeon Pro 560",
+      "vendor_name": "Apple",
+      "memory_size": 4096,
+      "api_type": "Metal",
+      "multi_threaded_rendering": true,
+      "version": "Metal",
+      "npot_support": "Full"
+    }
+  }
 }
 ```
 
@@ -470,31 +473,35 @@ The `type` and default key is `"state"`.
 
 : **Required**. Object with two keys: _Optional_ `type` for naming the state library (e.g.: Redux, MobX, Vuex) and **Required** `value` that holds the state object.
 
-Example:
+### Example State Context
 
 ```json
-"state": {
-  "state": {
-    "type": "MobX",
-    "value": {
-      "flights": [],
-      "airports": [],
-      "showModal": false
+{
+  "contexts": {
+    "state": {
+      "state": {
+        "type": "MobX",
+        "value": {
+          "flights": [],
+          "airports": [],
+          "showModal": false
+        }
+      }
     }
-  },
+  }
 }
 ```
 
 ## Culture Context
 
-Culture Context describes certain properties of the culture in which 
+Culture Context describes certain properties of the culture in which
 the software is used.
 
 The `type` and default key is `"culture"`.
 
 `calendar`
 
-: _Optional_. For example `GregorianCalendar`. Free form string. 
+: _Optional_. For example `GregorianCalendar`. Free form string.
 
 `display_name`
 
@@ -512,20 +519,77 @@ The `type` and default key is `"culture"`.
 
 : _Optional_. The timezone of the locale. For example, `Europe/Vienna`.
 
-## Examples
+## Cloud Resource Context
+
+Cloud Resource Context describes certain properties of cloud provider the software is running.
+The data in the context abides to the [Cloud](https://opentelemetry.io/docs/reference/specification/resource/semantic_conventions/cloud/) and [Host](https://opentelemetry.io/docs/reference/specification/resource/semantic_conventions/host/) semantic conventions of OpenTelemenetry.
+
+The `type` and default key is `"cloud_resource"`.
+
+`cloud.provider`
+
+: _Optional_. Name of the cloud provider.
+
+- List of well-known values. If one of them applies, then the respective value MUST be used, otherwise a custom value MAY be used:
+  - `alibaba_cloud` - Alibaba Cloud
+  - `aws` - Amazon Web Services
+  - `azure` - Microsoft Azure
+  - `gcp` - Google Cloud Platform
+  - `ibm_cloud` - IBM Cloud
+  - `tencent_cloud` - Tencent Cloud
+- Example: `aws`
+
+`cloud.account.id`
+
+: _Optional_. The cloud account ID the resource is assigned to.
+
+- Example: `111111111111`
+
+`cloud.region`
+
+: _Optional_. The geographical region the resource is running.
+
+- Example: `us-central1` or `us-east-1`
+
+`cloud.availability_zone`
+
+: _Optional_. Cloud regions often have multiple, isolated locations known as zones to increase availability. Availability zone represents the zone where the resource is running. In Google Cloud this is called `cloud.zone`.
+
+- Example: `us-east-1c`
+
+`cloud.platform`
+
+: _Optional_. The cloud platform in use. The prefix of the service SHOULD match the one specified in `cloud.provider`.
+
+- Example: `aws_ecs`
+
+`host.id`
+
+: _Optional_. Unique host ID.
+
+- Example: `3635354529892309001`
+
+`host.type`
+
+: _Optional_. Machine type of host.
+
+- Example: `t4g.medium`
+
+### Example Cloud Resource Context
 
 The following example illustrates the contexts part of the <Link to="/sdk/event-payloads/">event payload</Link> and omits other attributes for simplicity.
 
 ```json
 {
   "contexts": {
-    "os": {
-      "name": "Windows"
-    },
-    "electron": {
-      "type": "runtime",
-      "name": "Electron",
-      "version": "4.0"
+    "cloud_resource": {
+      "cloud.provider": "aws",
+      "cloud.platform": "aws_ec2",
+      "cloud.account.id": "499517922981",
+      "cloud.region": "us-east-1",
+      "cloud.availability_zone": "us-east-1e",
+      "host.id": "i-07d3301208fe0a55a",
+      "host.type": "t2.large"
     }
   }
 }