diff --git a/specification/resource/semantic_conventions/README.md b/specification/resource/semantic_conventions/README.md index 1b641bfd308..e4e45cdba7a 100644 --- a/specification/resource/semantic_conventions/README.md +++ b/specification/resource/semantic_conventions/README.md @@ -12,16 +12,9 @@ This document defines standard attributes for resources. These attributes are ty - [Service](#service) - [Telemetry SDK](#telemetry-sdk) - [Compute Unit](#compute-unit) - * [Container](#container) - * [Function as a Service](#function-as-a-service) - * [Process](#process) - [Deployment Service](#deployment-service) - * [Kubernetes](#kubernetes) - [Compute Instance](#compute-instance) - * [Host](#host) - [Environment](#environment) - * [Operating System](#operating-system) - * [Cloud](#cloud) - [Version Attributes](#version-attributes) @@ -90,141 +83,30 @@ The identifier SHOULD be stable across different versions of an implementation. ## Compute Unit -Attributes defining a compute unit (e.g. Container, Process, Function as a Service). +Attributes defining a compute unit (e.g. Container, Process, Function as a Service): -### Container - -**type:** `container` - -**Description:** A container instance. - -| Attribute | Description | Example | -|---|---|---| -| container.name | Container name. | `opentelemetry-autoconf` | -| container.id | Container id. Usually a UUID, as for example used to [identify Docker containers][]. The UUID might be abbreviated. | `a3bf90e006b2` | -| container.image.name | Name of the image the container was built on. | `gcr.io/opentelemetry/operator` | -| container.image.tag | Container image tag. | `0.1` | - -[identify Docker containers]: https://docs.docker.com/engine/reference/run/#container-identification - -### Function as a Service - -**type:** `faas` - -**Description:** A serverless instance. - -| Label | Description | Example | Required | -|---|---|---|--| -| faas.name | The name of the function being executed. | `my-function` | Yes | -| faas.id | The unique name of the function being executed.
For example, in AWS Lambda this field corresponds to the [ARN] value, in GCP to the URI of the resource, and in Azure to the [FunctionDirectory] field. | `arn:aws:lambda:us-west-2:123456789012:function:my-function` | Yes | -| faas.version | The version string of the function being executed as defined in [Version Attributes](#version-attributes). | `semver:2.0.0` | No | -| faas.instance | The execution environment ID as a string. | `my-function:instance-0001` | No | - -Note: The resource attribute `faas.instance` differs from the span attribute `faas.execution`. For more information see the [Semantic conventions for FaaS spans](../../trace/semantic_conventions/faas.md#difference-between-execution-and-instance). - -[ARN]:https://docs.aws.amazon.com/general/latest/gr/aws-arns-and-namespaces.html -[FunctionDirectory]: https://github.com/Azure/azure-functions-host/wiki/Retrieving-information-about-the-currently-running-function - -### Process - -**type:** `process` - -**Description:** An operating system process. - -| Attribute | Description | Example | Required | -|---|---|---|--| -| process.pid | Process identifier (PID). | `1234` | Yes | -| process.executable.name | The name of the process executable. On Linux based systems, can be set to the `Name` in `proc/[pid]/status`. On Windows, can be set to the base name of `GetProcessImageFileNameW`. | `otelcol` | See below | -| process.executable.path | The full path to the process executable. On Linux based systems, can be set to the target of `proc/[pid]/exe`. On Windows, can be set to the result of `GetProcessImageFileNameW`. | `/usr/bin/cmd/otelcol` | See below | -| process.command | The command used to launch the process (i.e. the command name). On Linux based systems, can be set to the zeroth string in `proc/[pid]/cmdline`. On Windows, can be set to the first parameter extracted from `GetCommandLineW`. | `cmd/otelcol` | See below | -| process.command_line | The full command used to launch the process. The value can be either a list of strings representing the ordered list of arguments, or a single string representing the full command. On Linux based systems, can be set to the list of null-delimited strings extracted from `proc/[pid]/cmdline`. On Windows, can be set to the result of `GetCommandLineW`. | Linux: `[ cmd/otecol, --config=config.yaml ]`, Windows: `cmd/otecol --config=config.yaml` | See below | -| process.owner | The username of the user that owns the process. | `root` | No | - -At least one of `process.executable.name`, `process.executable.path`, `process.command`, or `process.command_line` is required. +- [Container](./container.md) +- [Function as a Service](./faas.md) +- [Process](./process.md) ## Deployment Service -Attributes defining a deployment service (e.g. Kubernetes). - -### Kubernetes +Attributes defining a deployment service (e.g. Kubernetes): -**type:** `k8s` - -**Description:** A Kubernetes resource. - -| Attribute | Description | Example | -|---|---|---| -| k8s.cluster.name | The name of the cluster that the pod is running in. | `opentelemetry-cluster` | -| k8s.namespace.name | The name of the namespace that the pod is running in. | `default` | -| k8s.pod.name | The name of the pod. | `opentelemetry-pod-autoconf` | -| k8s.deployment.name | The name of the deployment. | `opentelemetry` | +- [Kubernetes](./k8s.md) ## Compute Instance -Attributes defining a computing instance (e.g. host). - -### Host - -**type:** `host` +Attributes defining a computing instance (e.g. host): -**Description:** A host is defined as a general computing instance. - -| Attribute | Description | Example | -|---|---|---| -| host.hostname | Hostname of the host.
It contains what the `hostname` command returns on the host machine. | `opentelemetry-test` | -| host.id | Unique host id.
For Cloud this must be the instance_id assigned by the cloud provider | `opentelemetry-test` | -| host.name | Name of the host.
It may contain what `hostname` returns on Unix systems, the fully qualified, or a name specified by the user. | `opentelemetry-test` | -| host.type | Type of host.
For Cloud this must be the machine type.| `n1-standard-1` | -| host.image.name | Name of the VM image or OS install the host was instantiated from. | `infra-ami-eks-worker-node-7d4ec78312`, `CentOS-8-x86_64-1905` | -| host.image.id | VM image id. For Cloud, this value is from the provider. | `ami-07b06b442921831e5` | -| host.image.version | The version string of the VM image as defined in [Version Attributes](#version-attributes). | `0.1` | +- [Host](./host.md) ## Environment -Attributes defining a running environment (e.g. Operating System, Cloud, Data Center). - -### Operating System - -**type:** `os` - -**Description**: The operating system (OS) on which the process represented by this resource is running. - -In case of virtualized environments, this is the operating system as it is observed by the process, i.e., the virtualized guest rather than the underlying host. - -| Attribute | Type | Description | Example | Required | -|---|---|---|---|---| -| `os.type` | string | The operating system type. | `"WINDOWS"` | Yes | -| `os.description` | string | Human readable (not intended to be parsed) OS version information, like e.g. reported by `ver` or `lsb_release -a` commands. | `"Microsoft Windows [Version 10.0.18363.778]"`
`"Ubuntu 18.04.1 LTS"` | No | - -`os.type` SHOULD be set to one of the values listed below. -If none of the listed values apply, a custom value best describing the family the operating system belongs to CAN be used. - -| Value | Description | -|---|---| -| `WINDOWS` | Microsoft Windows | -| `LINUX` | Linux | -| `DARWIN` | Apple Darwin | -| `FREEBSD` | FreeBSD | -| `NETBSD` | NetBSD| -| `OPENBSD` | OpenBSD | -| `DRAGONFLYBSD` | DragonFly BSD | -| `HPUX` | HP-UX (Hewlett Packard Unix) | -| `AIX` | AIX (Advanced Interactive eXecutive) | -| `SOLARIS` | Oracle Solaris | -| `ZOS` | IBM z/OS | - -### Cloud - -**type:** `cloud` - -**Description:** A cloud infrastructure (e.g. GCP, Azure, AWS). +Attributes defining a running environment (e.g. Operating System, Cloud, Data Center): -| Attribute | Description | Example | -|---|---|---| -| cloud.provider | Name of the cloud provider.
Example values are aws, azure, gcp. | `gcp` | -| cloud.account.id | The cloud account id used to identify different entities. | `opentelemetry` | -| cloud.region | A specific geographical location where different entities can run | `us-central1` | -| cloud.zone | Zones are a sub set of the region connected through low-latency links.
In aws it is called availability-zone. | `us-central1-a` | +- [Operating System](./os.md) +- [Cloud](./cloud.md) ## Version Attributes diff --git a/specification/resource/semantic_conventions/cloud.md b/specification/resource/semantic_conventions/cloud.md new file mode 100644 index 00000000000..961a0f02339 --- /dev/null +++ b/specification/resource/semantic_conventions/cloud.md @@ -0,0 +1,12 @@ +# Cloud + +**type:** `cloud` + +**Description:** A cloud infrastructure (e.g. GCP, Azure, AWS). + +| Attribute | Description | Example | +|---|---|---| +| cloud.provider | Name of the cloud provider.
Example values are aws, azure, gcp. | `gcp` | +| cloud.account.id | The cloud account id used to identify different entities. | `opentelemetry` | +| cloud.region | A specific geographical location where different entities can run | `us-central1` | +| cloud.zone | Zones are a sub set of the region connected through low-latency links.
In aws it is called availability-zone. | `us-central1-a` | diff --git a/specification/resource/semantic_conventions/container.md b/specification/resource/semantic_conventions/container.md new file mode 100644 index 00000000000..78cbce23291 --- /dev/null +++ b/specification/resource/semantic_conventions/container.md @@ -0,0 +1,14 @@ +# Container + +**type:** `container` + +**Description:** A container instance. + +| Attribute | Description | Example | +|---|---|---| +| container.name | Container name. | `opentelemetry-autoconf` | +| container.id | Container id. Usually a UUID, as for example used to [identify Docker containers][]. The UUID might be abbreviated. | `a3bf90e006b2` | +| container.image.name | Name of the image the container was built on. | `gcr.io/opentelemetry/operator` | +| container.image.tag | Container image tag. | `0.1` | + +[identify Docker containers]: https://docs.docker.com/engine/reference/run/#container-identification diff --git a/specification/resource/semantic_conventions/faas.md b/specification/resource/semantic_conventions/faas.md new file mode 100644 index 00000000000..50f32adcdcd --- /dev/null +++ b/specification/resource/semantic_conventions/faas.md @@ -0,0 +1,17 @@ +# Function as a Service + +**type:** `faas` + +**Description:** A serverless instance. + +| Label | Description | Example | Required | +|---|---|---|--| +| faas.name | The name of the function being executed. | `my-function` | Yes | +| faas.id | The unique name of the function being executed.
For example, in AWS Lambda this field corresponds to the [ARN] value, in GCP to the URI of the resource, and in Azure to the [FunctionDirectory] field. | `arn:aws:lambda:us-west-2:123456789012:function:my-function` | Yes | +| faas.version | The version string of the function being executed as defined in [Version Attributes](#version-attributes). | `semver:2.0.0` | No | +| faas.instance | The execution environment ID as a string. | `my-function:instance-0001` | No | + +Note: The resource attribute `faas.instance` differs from the span attribute `faas.execution`. For more information see the [Semantic conventions for FaaS spans](../../trace/semantic_conventions/faas.md#difference-between-execution-and-instance). + +[ARN]:https://docs.aws.amazon.com/general/latest/gr/aws-arns-and-namespaces.html +[FunctionDirectory]: https://github.com/Azure/azure-functions-host/wiki/Retrieving-information-about-the-currently-running-function diff --git a/specification/resource/semantic_conventions/host.md b/specification/resource/semantic_conventions/host.md new file mode 100644 index 00000000000..98150b78487 --- /dev/null +++ b/specification/resource/semantic_conventions/host.md @@ -0,0 +1,15 @@ +# Host + +**type:** `host` + +**Description:** A host is defined as a general computing instance. + +| Attribute | Description | Example | +|---|---|---| +| host.hostname | Hostname of the host.
It contains what the `hostname` command returns on the host machine. | `opentelemetry-test` | +| host.id | Unique host id.
For Cloud this must be the instance_id assigned by the cloud provider | `opentelemetry-test` | +| host.name | Name of the host.
It may contain what `hostname` returns on Unix systems, the fully qualified, or a name specified by the user. | `opentelemetry-test` | +| host.type | Type of host.
For Cloud this must be the machine type.| `n1-standard-1` | +| host.image.name | Name of the VM image or OS install the host was instantiated from. | `infra-ami-eks-worker-node-7d4ec78312`, `CentOS-8-x86_64-1905` | +| host.image.id | VM image id. For Cloud, this value is from the provider. | `ami-07b06b442921831e5` | +| host.image.version | The version string of the VM image as defined in [Version Attributes](#version-attributes). | `0.1` | diff --git a/specification/resource/semantic_conventions/k8s.md b/specification/resource/semantic_conventions/k8s.md new file mode 100644 index 00000000000..701a3d8a840 --- /dev/null +++ b/specification/resource/semantic_conventions/k8s.md @@ -0,0 +1,12 @@ +# Kubernetes + +**type:** `k8s` + +**Description:** A Kubernetes resource. + +| Attribute | Description | Example | +|---|---|---| +| k8s.cluster.name | The name of the cluster that the pod is running in. | `opentelemetry-cluster` | +| k8s.namespace.name | The name of the namespace that the pod is running in. | `default` | +| k8s.pod.name | The name of the pod. | `opentelemetry-pod-autoconf` | +| k8s.deployment.name | The name of the deployment. | `opentelemetry` | diff --git a/specification/resource/semantic_conventions/os.md b/specification/resource/semantic_conventions/os.md new file mode 100644 index 00000000000..111f9270d28 --- /dev/null +++ b/specification/resource/semantic_conventions/os.md @@ -0,0 +1,29 @@ +# Operating System + +**type:** `os` + +**Description**: The operating system (OS) on which the process represented by this resource is running. + +In case of virtualized environments, this is the operating system as it is observed by the process, i.e., the virtualized guest rather than the underlying host. + +| Attribute | Type | Description | Example | Required | +|---|---|---|---|---| +| `os.type` | string | The operating system type. | `"WINDOWS"` | Yes | +| `os.description` | string | Human readable (not intended to be parsed) OS version information, like e.g. reported by `ver` or `lsb_release -a` commands. | `"Microsoft Windows [Version 10.0.18363.778]"`
`"Ubuntu 18.04.1 LTS"` | No | + +`os.type` SHOULD be set to one of the values listed below. +If none of the listed values apply, a custom value best describing the family the operating system belongs to CAN be used. + +| Value | Description | +|---|---| +| `WINDOWS` | Microsoft Windows | +| `LINUX` | Linux | +| `DARWIN` | Apple Darwin | +| `FREEBSD` | FreeBSD | +| `NETBSD` | NetBSD| +| `OPENBSD` | OpenBSD | +| `DRAGONFLYBSD` | DragonFly BSD | +| `HPUX` | HP-UX (Hewlett Packard Unix) | +| `AIX` | AIX (Advanced Interactive eXecutive) | +| `SOLARIS` | Oracle Solaris | +| `ZOS` | IBM z/OS | diff --git a/specification/resource/semantic_conventions/process.md b/specification/resource/semantic_conventions/process.md new file mode 100644 index 00000000000..ff72942c3a9 --- /dev/null +++ b/specification/resource/semantic_conventions/process.md @@ -0,0 +1,16 @@ +# Process + +**type:** `process` + +**Description:** An operating system process. + +| Attribute | Description | Example | Required | +|---|---|---|--| +| process.pid | Process identifier (PID). | `1234` | Yes | +| process.executable.name | The name of the process executable. On Linux based systems, can be set to the `Name` in `proc/[pid]/status`. On Windows, can be set to the base name of `GetProcessImageFileNameW`. | `otelcol` | See below | +| process.executable.path | The full path to the process executable. On Linux based systems, can be set to the target of `proc/[pid]/exe`. On Windows, can be set to the result of `GetProcessImageFileNameW`. | `/usr/bin/cmd/otelcol` | See below | +| process.command | The command used to launch the process (i.e. the command name). On Linux based systems, can be set to the zeroth string in `proc/[pid]/cmdline`. On Windows, can be set to the first parameter extracted from `GetCommandLineW`. | `cmd/otelcol` | See below | +| process.command_line | The full command used to launch the process. The value can be either a list of strings representing the ordered list of arguments, or a single string representing the full command. On Linux based systems, can be set to the list of null-delimited strings extracted from `proc/[pid]/cmdline`. On Windows, can be set to the result of `GetCommandLineW`. | Linux: `[ cmd/otecol, --config=config.yaml ]`, Windows: `cmd/otecol --config=config.yaml` | See below | +| process.owner | The username of the user that owns the process. | `root` | No | + +At least one of `process.executable.name`, `process.executable.path`, `process.command`, or `process.command_line` is required.