Merge pull request #17188 from alanwest/alanwest/otel-entities

Improve OpenTelemetry entity documentation

src/content/docs/more-integrations/open-source-telemetry-integrations/opentelemetry/best-practices/opentelemetry-best-practices-resources.mdx

@@ -8,21 +8,118 @@ metaDescription: Here are some tips for working with OpenTelemetry resources and
 freshnessValidatedDate: never
 ---
 
-A resource in OpenTelemetry represents information about an entity generating telemetry data. Make sure all telemetry data sent to New Relic is associated with a resource so it can be linked with the appropriate entity in New Relic. The [OpenTelemetry Resource SDK specification](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/resource/sdk.md) defines the functionality implemented by all language SDKs for defining a resource.
+All data from OpenTelemetry is associated with a [resource](https://opentelemetry.io/docs/concepts/resources).
+A resource is a representation of the entity producing telemetry as resource
+attributes. The resource attributes are used to adapt a resource to New Relic's
+notion of an [entity](docs/new-relic-solutions/new-relic-one/core-concepts/what-entity-new-relic).
 
-The following suites of attributes are defined by the [OpenTelemetry resource semantic conventions](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/semantic-conventions.md). These attributes are usually set by creating a resource using the OpenTelemetry SDK.
+Data received is associated with an entity through a process called [entity synthesis](/docs/entities/synthesis/)
+whereby the resource attributes present are matched to rules which determine the type of entity the
+data will be associated with. For data sourced from OpenTelemetry, the entity synthesis rules are
+designed to respect the OpenTelemetry [resource semantic conventions](https://opentelemetry.io/docs/specs/semconv/resource).
 
-* `service.* attributes`
-  * `service.name` attribute is required to associate your resource with an entity in the UI 
-  * `service.instance.id` is required for certain panes to light up
-* `telemetry.sdk.language=java` is required to see data in the JVM section 
+The resource semantic conventions define different bodies of conventions for
+describing different types of entities. For example, the
+[service](https://opentelemetry.io/docs/specs/semconv/resource/#service) and
+[host](https://opentelemetry.io/docs/specs/semconv/resource/host/)
+conventions define the resource attributes which describe a service or host instance,
+respectively.
 
-## Organize your entities in the UI using tags [#tags]
+## Supported entity types [#supported-entity-types]
 
-You can use tags to organize and filter your entities in the UI. [Tags](/docs/new-relic-solutions/new-relic-one/core-concepts/use-tags-help-organize-find-your-data/) are key-value pairs, for example `team: operations`, added to various sets of data, like monitored apps and hosts. Certain important attributes are automatically available as tags, such as account ID; you can also add your own custom tags [directly in the UI](/docs/new-relic-solutions/new-relic-one/core-concepts/use-tags-help-organize-find-your-data/#add-tags), or with one of the methods below.
+Described here are the New Relic entity types which are supported when using
+OpenTelemetry instrumentation. Included for each supported entity type are:
 
-Use the [resource processor](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/processor/resourceprocessor) to add resource attributes prefixed with `tags`, which will result in a tag on your entity in New Relic. For example, adding the attribute `tags.mytag=myvalue` will result in the entity tag `mytag=myvalue`. Here’s an example configuration:
+* The resource attributes required for entity synthesis.
+* Recommended attributes that drive certain aspects of the New Relic UI.
+* Attributes which become [entity tags](/docs/new-relic-solutions/new-relic-one/core-concepts/use-tags-help-organize-find-your-data/),
+   when present.
 
-<img width="254" alt="Screen Shot 2022-08-15 at 2 22 34 PM" src="https://user-images.githubusercontent.com/48657837/184720791-d2040326-55e6-4932-a4da-87d5ed4e6801.png"/>
+### Services [#services]
 
-You can also add resource attributes directly in the resource builder in your SDK (check your language SDK repo for how to do this, and remember to use the prefix `tags.`), or export them as [environment variables](https://opentelemetry.io/docs/concepts/sdk-configuration/general-sdk-configuration/#otel_resource_attributes). 
+A service entity is synthesized by adhering to the OpenTelemetry resource
+semantic conventions describing a
+[service instance](https://opentelemetry.io/docs/specs/semconv/resource/#service).
+
+Refer to our
+[documentation and examples](/docs/more-integrations/open-source-telemetry-integrations/opentelemetry/get-started/opentelemetry-set-up-your-app)
+for monitoring service entities using OpenTelemetry.
+
+#### Required attributes
+
+* [`service.name`](https://opentelemetry.io/docs/specs/semconv/attributes-registry/service): The entity name you see in the UI comes from this value.
+* [`host.name`](https://opentelemetry.io/docs/specs/semconv/attributes-registry/host/): The host name you see in the UI comes from this value.
+
+#### Recommended attributes [#recommended-attributes]
+
+* [`service.instance.id`](https://opentelemetry.io/docs/specs/semconv/attributes-registry/service)
+  * Enables faceting between multiple instances of the same service.
+* [`telemetry.sdk.language`](https://opentelemetry.io/docs/specs/semconv/attributes-registry/telemetry)
+  * When present, drives the display of any runtime specific UI. For example,
+    the JVM runtime page for Java applications.
+
+#### Entity tags [#entity-tags]
+
+* [`service.namespace`](https://opentelemetry.io/docs/specs/semconv/attributes-registry/service)
+* [`telemetry.sdk.language`](https://opentelemetry.io/docs/specs/semconv/attributes-registry/telemetry) (added as language tag)
+* [`telemetry.sdk.version`](https://opentelemetry.io/docs/specs/semconv/attributes-registry/telemetry)
+* [`k8s.cluster.name`](https://opentelemetry.io/docs/specs/semconv/attributes-registry/k8s)
+* [`k8s.namespace.name`](https://opentelemetry.io/docs/specs/semconv/attributes-registry/k8s)
+* [`k8s.deployment.name`](https://opentelemetry.io/docs/specs/semconv/attributes-registry/k8s)
+
+### Hosts [#hosts]
+
+A host entity is synthesized by adhering to the OpenTelemetry resource semantic
+conventions describing a [host](https://opentelemetry.io/docs/specs/semconv/resource/host).
+
+Refer to our
+[documentation](/docs/more-integrations/open-source-telemetry-integrations/opentelemetry/collector/opentelemetry-collector-infra-hosts)
+for monitoring host entities using the host metrics receiver for the OpenTelemetry collector.
+
+#### Required attributes [#required-attributes]
+
+* [`host.name`](https://opentelemetry.io/docs/specs/semconv/attributes-registry/host)
+* [`host.id`](https://opentelemetry.io/docs/specs/semconv/attributes-registry/host)
+
+#### Entity tags [#entity-tags]
+
+* [`cloud.provider`](https://opentelemetry.io/docs/specs/semconv/attributes-registry/cloud)
+* [`cloud.account.id`](https://opentelemetry.io/docs/specs/semconv/attributes-registry/cloud)
+* [`cloud.region`](https://opentelemetry.io/docs/specs/semconv/attributes-registry/cloud)
+* [`cloud.availability_zone`](https://opentelemetry.io/docs/specs/semconv/attributes-registry/cloud)
+* [`cloud.platform`](https://opentelemetry.io/docs/specs/semconv/attributes-registry/cloud)
+* [`host.id`](https://opentelemetry.io/docs/specs/semconv/attributes-registry/host)
+* [`host.name`](https://opentelemetry.io/docs/specs/semconv/attributes-registry/host)
+* [`host.type`](https://opentelemetry.io/docs/specs/semconv/attributes-registry/host)
+* [`host.arch`](https://opentelemetry.io/docs/specs/semconv/attributes-registry/host)
+* [`host.image.name`](https://opentelemetry.io/docs/specs/semconv/attributes-registry/host)
+* [`host.image.id`](https://opentelemetry.io/docs/specs/semconv/attributes-registry/host)
+* [`host.image.version`](https://opentelemetry.io/docs/specs/semconv/attributes-registry/host)
+
+## Supported entity relationships [#supported-entity-relationships]
+
+New Relic supports relationships between entities sourced from
+OpenTelemetry instrumentation. These relationships are synthesized
+automatically when the appropriate relationship criteria is met. Below are the
+relationships that are currently supported and their required criteria.
+
+### Service to host [#service-to-host]
+
+Relationships between a service and host entity require that the service
+includes the `host.id` resource attribute and that it matches the `host.id` of
+the host it is running on.
+
+## Adding custom tags to an entity [#tags]
+
+You can use tags to organize and filter your entities in the UI.
+[Tags](/docs/new-relic-solutions/new-relic-one/core-concepts/use-tags-help-organize-find-your-data/)
+are key-value pairs, for example `team: operations`, added to various sets of
+data, like monitored apps and hosts. Certain important attributes are
+automatically available as tags, such as account ID; you can also add your own
+custom tags
+[directly in the UI](/docs/new-relic-solutions/new-relic-one/core-concepts/use-tags-help-organize-find-your-data/#add-tags),
+or with one of the methods below.
+
+Adding resource attributes prefixed with `tags` will result in a tag on your
+entity in New Relic. For example, adding the attribute `tags.mytag=myvalue`
+will result in the entity tag `mytag=myvalue`.

src/content/docs/new-relic-solutions/new-relic-one/core-concepts/use-tags-help-organize-find-your-data.mdx

@@ -115,21 +115,6 @@ You can also programmatically automate tags using our [API](/docs/apis/nerdgraph
 
   </Collapser>
 
-  <Collapser
-    id="tags-from-agent-host"
-    title="OpenTelemetry resource attribute tags"
-  >
-    Certain [OpenTelemetry resource attributes](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/resource/semantic_conventions/README.md) are automatically applied as entity tags. When the following attributes are present on span data associated with a service entity, they will be attached to that entity:
-
-        * `k8s.cluster.name`
-        * `k8s.deployment.name`
-        * `k8s.namespace.name`
-        * `telemetry.sdk.language`: Will be stored as a tag named `language`
-        * `telemetry.sdk.version`
-        * `service.namespace`
-
-    This automated tagging is done using New Relic entity synthesis, which is [documented on GitHub](https://github.com/newrelic/entity-definitions#entity-definitions). In the case of OpenTelemetry services, the [tagging definitions](https://github.com/newrelic/entity-definitions/blob/main/definitions/ext-service/definition.yml#L58) are on `ext-service` entities.
-  </Collapser>
 </CollapserGroup>
 
 ## Manage tags [#tag-management]