diff --git a/src/content/docs/opentelemetry/best-practices/opentelemetry-best-practices-resources.mdx b/src/content/docs/opentelemetry/best-practices/opentelemetry-best-practices-resources.mdx index 244ce331699..b9991daf2b3 100644 --- a/src/content/docs/opentelemetry/best-practices/opentelemetry-best-practices-resources.mdx +++ b/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] + + +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. + + +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