Add concept page for resources (open-telemetry#3365)

Co-authored-by: Phillip Carter <pcarter@fastmail.com>

Author: svrnm

.gitignore

@@ -1,7 +1,7 @@
 # Hugo-generated assets
 .hugo_build.lock
 /public
-resources/
+/resources
 
 # npm assets
 node_modules/

.textlintrc.json

@@ -12,6 +12,7 @@
     "allowlist": {
       "allow": [
         "/{{%.*%}}/",
+        "/{{.*-}}/",
         "/<http://.*>/",
         "medium.com/opentelemetry",
         "github.com/open-telemetry",

content/en/docs/concepts/components.md

@@ -88,15 +88,18 @@ For more information, see
 
 ### Resource Detectors
 
-A resource represents the entity producing telemetry as resource attributes. For
-example, a process producing telemetry that is running in a container on
-Kubernetes has a Pod name, a namespace, and possibly a deployment name. All
-three of these attributes can be included in the resource.
+A [resource](/docs/concepts/resources/) represents the entity producing
+telemetry as resource attributes. For example, a process producing telemetry
+that is running in a container on Kubernetes has a Pod name, a namespace, and
+possibly a deployment name. All three of these attributes can be included in the
+resource.
 
 The language specific implementations of OpenTelemetry provide resource
-detection from the environment variable OTEL_RESOURCE_DETECTION and for many
+detection from the environment variable `OTEL_RESOURCE_ATTRIBUTES` and for many
 common entities, like process runtime, service, host or operating system.
 
+For more information, see [Resources](/docs/concepts/resources/).
+
 ### Cross Service Propagators
 
 Propagation is the mechanism that moves data between services and processes.

content/en/docs/concepts/distributions.md

@@ -3,7 +3,7 @@ title: Distributions
 description: >-
   A distribution, not to be confused with a fork, is customized version of an
   OpenTelemetry component.
-weight: 90
+weight: 190
 ---
 
 The OpenTelemetry projects consists of multiple [components](../components) that

content/en/docs/concepts/glossary.md

@@ -3,7 +3,7 @@ title: Glossary
 description: >-
   Terminology you may or may not be familiar with used by the OpenTelemetry
   project.
-weight: 100
+weight: 200
 ---
 
 The OpenTelemetry project uses terminology you may or may not be familiar with.

content/en/docs/concepts/resources/_index.md

@@ -0,0 +1,58 @@
+---
+title: Resources
+weight: 70
+---
+
+## Introduction
+
+{{% docs/instrumentation/resources-intro %}}
+
+If you use [Jaeger](https://www.jaegertracing.io/) as your observability
+backend, resource attributes are grouped under the **Process** tab:
+
+![A screenshot from Jaeger showing an example output of resource attributes associated to a trace](screenshot-jaeger-resources.png)
+
+A resource is added to the `TraceProvider` or `MetricProvider` when they are
+created during initialization. This association can not be changed later. After
+a resource is added, all spans and metrics produced from a `Tracer` or `Meter`
+from the provider will have the resource associated with them.
+
+## Semantic Attributes with SDK-provided Default Value
+
+There are attributes provided by the OpenTelemetry SDK. One of them is the
+`service.name`, which represents the logical name of the service. By default,
+SDKs will assign the value `unknown_service` for this value, so it is
+recommended to set it explicitly, either in code or via setting the environment
+variable `OTEL_SERVICE_NAME`.
+
+Additionally, the SDK will also provides the following resource attributes to
+identify itself: `telemetry.sdk.name`, `telemetry.sdk.language` and
+`telemetry.sdk.version`.
+
+## Resource Detectors
+
+Most language-specific SDKs provide a set of resource detectors that can be used
+to automatically detect resource information from the environment. Common
+resource detectors include:
+
+- [Operating System](/docs/specs/semconv/resource/os/)
+- [Host](/docs/specs/semconv/resource/host/)
+- [Process and Process Runtime](/docs/specs/semconv/resource/process/)
+- [Container](/docs/specs/semconv/resource/container/)
+- [Kubernetes](/docs/specs/semconv/resource/k8s/)
+- [Cloud-Provider-Specific Attributes](/docs/specs/semconv/resource/#cloud-provider-specific-attributes)
+- [and more](/docs/specs/semconv/resource/)
+
+## Custom resources
+
+You can also provide your own resource attributes. You can either provide them
+in code or via populating the environment variable `OTEL_RESOURCE_ATTRIBUTES`.
+If applicable, use the
+[semantic conventions for your resource attributes](/docs/specs/semconv/resource).
+For example, you can provide the name of your
+[deployment environment](/docs/specs/semconv/resource/deployment-environment/)
+using `deployment.environment`:
+
+```shell
+env OTEL_RESOURCE_ATTRIBUTES=deployment.environment=production yourApp
+```

content/en/docs/concepts/resources/screenshot-jaeger-resources.png

@@ -3,7 +3,7 @@ title: Sampling
 description:
   Learn about sampling, and the different sampling options available in
   OpenTelemetry.
-weight: 50
+weight: 80
 ---
 
 With distributed tracing, you observe requests as they move from one service to

content/en/docs/concepts/sampling/index.md

@@ -1,6 +1,6 @@
 ---
 title: SDK Configuration
-weight: 51
+weight: 101
 ---
 
 OpenTelemetry SDKs support configuration in each language and with environment

content/en/docs/concepts/sdk-configuration/_index.md

@@ -9,16 +9,7 @@ cSpell:ignore: behaviour
 <!-- markdownlint-disable no-duplicate-heading -->
 <!-- markdownlint-capture -->
 
-A [resource](/docs/specs/otel/overview/#resources) represents an entity
-producing telemetry as attributes. For example, an OTP Release producing
-telemetry that is running in a container on Kubernetes has an OTP Release name,
-a Pod name, a namespace, and possibly a deployment name. All four of these
-attributes can be included in the resource.
-
-In your observability backend, you can use resource information to better
-investigate interesting behavior. For example, if your trace or metrics data
-indicate latency in your system, you can narrow it down to a specific container,
-pod, or Kubernetes deployment.
+{{% docs/instrumentation/resources-intro "an OTP Release" %}}
 
 ## Using resource detectors
 

content/en/docs/instrumentation/erlang/resources.md

@@ -4,10 +4,7 @@ weight: 70
 cSpell:ignore: sdktrace thirdparty
 ---
 
-Resources are a special type of attribute that apply to all spans generated by a
-process. These should be used to represent underlying metadata about a process
-that's non-ephemeral — for example, the hostname of a process, or its
-instance ID.
+{{% docs/instrumentation/resources-intro %}}
 
 Resources should be assigned to a tracer provider at its initialization, and are
 created much like attributes:

content/en/docs/instrumentation/go/resources.md

@@ -4,16 +4,7 @@ weight: 70
 cSpell:ignore: getenv myhost SIGINT uuidgen WORKDIR
 ---
 
-A [resource](/docs/specs/otel/resource/sdk/) represents the entity producing
-telemetry as resource attributes. For example, a process producing telemetry
-that is running in a container on Kubernetes has a Pod name, a namespace, and
-possibly a deployment name. All three of these attributes can be included in the
-resource.
-
-In your observability backend, you can use resource information to better
-investigate interesting behavior. For example, if your trace or metrics data
-indicate latency in your system, you can narrow it down to a specific container,
-pod, or Kubernetes deployment.
+{{% docs/instrumentation/resources-intro %}}
 
 If you use the Javaagent for
 [automatic instrumentation](/docs/instrumentation/java/automatic) you can learn

content/en/docs/instrumentation/java/resources.md

@@ -5,18 +5,10 @@ cSpell:ignore: myhost SIGINT uuidgen WORKDIR
 description: Add details about your applications' environment to your telemetry
 ---
 
-A [resource][] represents the entity producing telemetry as resource attributes.
-For example, a process producing telemetry that is running in a container on
-Kubernetes has a Pod name, a namespace, and possibly a deployment name. All
-three of these attributes can be included in the resource.
+{{% docs/instrumentation/resources-intro %}}
 
-In your observability backend, you can use resource information to better
-investigate interesting behavior. For example, if your trace or metrics data
-indicate latency in your system, you can narrow it down to a specific container,
-pod, or Kubernetes deployment.
-
-Below you will find some introductions on how to set up resource detection with
-the Node.js SDK.
+Below you will find introductions on how to set up resource detection with the
+Node.js SDK.
 
 ## Setup
 
@@ -261,7 +253,6 @@ to get details about your [Cloud] environment or [Deployment][]. You will find a
 list
 [here](https://github.com/open-telemetry/opentelemetry-js-contrib/tree/main/detectors/node).
 
-[resource]: /docs/specs/otel/resource/sdk/
 [getting started - node.js]: /docs/instrumentation/js/getting-started/nodejs/
 [process and process runtime resources]:
   /docs/specs/otel/resource/semantic_conventions/process/

content/en/docs/instrumentation/js/resources.md

@@ -4,15 +4,7 @@ weight: 70
 cSpell:ignore: myhost pcarter uuidgen
 ---
 
-A [resource][] represents the entity producing telemetry as resource attributes.
-For example, a process producing telemetry that is running in a container on
-Kubernetes has a Pod name, a namespace, and possibly a deployment name. All
-three of these attributes can be included in the resource.
-
-In your observability backend, you can use resource information to better
-investigate interesting behavior. For example, if your trace or metrics data
-indicate latency in your system, you can narrow it down to a specific container,
-pod, or Kubernetes deployment.
+{{% docs/instrumentation/resources-intro %}}
 
 ## Setup
 
@@ -145,7 +137,6 @@ code, the values in code take precedence.
 There are more resource detectors you can add to your configuration, for example
 to get details about your [Cloud] environment or [Deployment][].
 
-[resource]: /docs/specs/otel/resource/sdk/
 [getting started]: /docs/instrumentation/net/getting-started/
 [host]: /docs/specs/otel/resource/semantic_conventions/host/
 [cloud]: /docs/specs/otel/resource/semantic_conventions/cloud/

content/en/docs/instrumentation/net/resources.md

@@ -3,15 +3,7 @@ title: Resources
 weight: 70
 ---
 
-A resource represents the entity producing telemetry as resource attributes. For
-example, a process producing telemetry that is running in a container on
-Kubernetes has a Pod name, a namespace, and possibly a deployment name. All
-three of these attributes can be included in the resource.
-
-In your observability backend, you can use resource information to better
-investigate interesting behavior. For example, if your trace or metrics data
-indicate latency in your system, you can narrow it down to a specific container,
-pod, or Kubernetes deployment.
+{{% docs/instrumentation/resources-intro %}}
 
 ## Resource Detection
 

content/en/docs/instrumentation/php/resources.md

@@ -0,0 +1,16 @@
+{{ $processWord := default ("a process") (.Get 0)  -}}
+{{ $resourceHRef := "/docs/concepts/resources/" }}
+
+{{ if eq .Page.RelPermalink $resourceHRef }}
+{{ $resourceHRef = "/docs/specs/otel/resource/sdk/" }} {{ end -}}
+
+A [resource]({{ $resourceHRef }}) represents the entity producing telemetry as
+resource attributes. For example, {{ $processWord }} producing telemetry that is
+running in a container on Kubernetes has {{ $processWord }} name, a pod name, a
+namespace, and possibly a deployment name. All four of these attributes can be
+included in the resource.
+
+In your observability backend, you can use resource information to better
+investigate interesting behavior. For example, if your trace or metrics data
+indicate latency in your system, you can narrow it down to a specific container,
+pod, or Kubernetes deployment.