OTel service to infra agent entity relationships

src/content/docs/opentelemetry/best-practices/opentelemetry-best-practices-resources.mdx

@@ -122,12 +122,110 @@ 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]
+### Service to infrastructure relationships using the OpenTelemetry Collector [#service-to-infra-otel-collector]
+
+The OpenTelemetry Collector can be used to
+[monitor your infrastructure](/docs/opentelemetry/get-started/collector-infra-monitoring/opentelemetry-collector-infra-intro).
+Entity relationships are supported between OpenTelemetry instrumented services
+the infrastructure entities created from the OpenTelemetry Collector.
+
+The following relationships to your services are supported:
+
+* [Hosts](#service-to-host)
+* [Containers](#service-to-container)
+
+#### Hosts [#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.
 
+#### Containers [#service-to-container]
+
+Relationships between a service and container entity require that the service
+includes the `container.id` resource attribute and that it matches the
+`container.id` of the container it is running in.
+
+### Service to infrastructure relationships using the New Relic infrastructure agent [#service-to-infra-nr-infra-agent]
+
+The [New Relic infrastructure agent](/docs/infrastructure/choose-infra-install-method)
+can be used to monitor your infrastructure. Entity relationships are supported
+between OpenTelemetry instrumented services and infrastructure entities created
+from the New Relic infrastructure agent.
+
+For these relationships to work, the telemetry emitted from your service must
+be configured so that it can be correlated with the telemetry emitted by the
+infrastructure agent. This requires the telemetry of your service to include
+resource attributes that identify the host, container, etc that the service is
+running on. This is usually as easy as configuring [resource detectors](https://opentelemetry.io/docs/concepts/resources/#resource-detectors)
+provided by the OpenTelemetry SDK for your language or using the OpenTelemetry
+Collector's [resource detection processor](https://github.com/open-telemetry/opentelemetry-collector-contrib/blob/main/processor/resourcedetectionprocessor/README.md).
+
+The following relationships to your services are supported:
+
+* [Hosts](#service-to-infra-nr-infra-agent-hosts)
+* [Containers](#service-to-infra-nr-infra-agent-containers)
+
+#### Hosts monitored with the New Relic infrastructure agent [#service-to-infra-nr-infra-agent-hosts]
+
+Host relationships between OpenTelemetry instrumented services and host
+entities generated from the New Relic infrastructure agent require two things:
+
+* The `host.id` resource attribute must be present on the telemetry from the
+  service.
+* The `host.id` must correlate with the [host's identity](#service-to-infra-nr-infra-derive-host-identity)
+  derived by the infrastructure agent.
+
+##### Deriving host identity [#service-to-infra-nr-infra-derive-host-identity]
+
+<Callout variant="important">
+The host identity derived by the New Relic infrastructure agent does not
+exactly match the semantics of OpenTelemetry's `host.id` resource attribute
+in all circumstances. This can cause difficulties in correlating services to
+hosts monitored with the infrastructure agent. Read this section carefully to
+understand potential challenges.
+</Callout>
+
+The host identity derived by the New Relic infrastructure agent depends on
+hosting environment and agent configuration.
+
+For services to be properly correlated to hosts monitored by the New Relic
+infrastructure agent, the `host.id` resource attribute emitted by the service
+must match the host identity computed by the agent. The following sections
+describe, in priority order, how the infrastructure agent computes a host's
+identity so that you can understand how to properly set the service's
+`host.id`.
+
+###### Infrastructure agent configured with a `display_name` [#service-to-infra-nr-infra-display-name]
+
+If the infrastructure agent is configured to use a [`display_name`](/docs/infrastructure/infrastructure-agent/configuration/infrastructure-agent-configuration-settings/#display-name)
+then it will use that as the host's identity. Your OpenTelemetry instrumented
+service must be configured to emit a `host.id` that is equal to the
+`display_name`.
+
+###### Host running in a cloud environment [#service-to-infra-nr-infra-cloud-environment]
+
+If the host is running in a cloud environment (e.g., AWS or Azure) then the
+agent will use the instance ID assigned by the cloud provider. Your
+OpenTelemetry instrumented service should be configured to use a resource
+detector appropriate for your cloud environment.
+
+###### Host running in a non-cloud environment [#service-to-infra-nr-infra-non-cloud]
+
+In non-containerized environments the infrastructure agent computes a
+fully-qualified domain name (FQDN) of the host. How the agent determines the
+FQDN differs based on a variety of factors such as the operating system.
+Resource detectors cannot be relied on to compute the same value as the FQDN
+resolved by the infrastructure agent. It is recommended that you explicitly
+configure a `display_name` for the infrastructure agent and the `host.id` of
+your service so that they match.
+
+#### Service to containers monitored with the New Relic infrastructure agent [#service-to-infra-nr-infra-agent-containers]
+
+Relationships between a service and container entity require that the service
+be configured with an appropriate resource detector that includes the
+`container.id` resource attribute.
+
 ### Amazon CloudWatch Metric Streams
 
 Your infrastructure hosted in AWS can be monitored with New Relic's integration