From d78ce58b4e2628bbff39c3116b2a99788cafd99e Mon Sep 17 00:00:00 2001 From: Alan West <3676547+alanwest@users.noreply.github.com> Date: Tue, 4 Feb 2025 14:13:53 -0800 Subject: [PATCH 1/4] OTel service to infra agent entity relationships --- ...opentelemetry-best-practices-resources.mdx | 85 ++++++++++++++++++- 1 file changed, 84 insertions(+), 1 deletion(-) 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..56a6321e815 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,95 @@ 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 + +The following relationships between services and infrastructure are supported: + +* [Hosts](#service-to-host) + +#### 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. +### Service to infrastructure relationships using the New Relic infrastructure agent [#service-to-infra-nr-infra-agent] + +Entity relationships are supported between OpenTelemetry instrumented services +and infrastructure entities created by 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 between services and infrastructure 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: + +1. The `host.id` resource attribute must be present on the telemetry from the + service. +2. The `host.id` must correlate with the host's identity derived by + the infrastructure agent. + + +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 the following section +carefully to understand potential challenges. + + +##### Computing host identity + +The host identity computed 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` + +If the infrastructure agent is configured to use a `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 + +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 + +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 From 226c247e0a4f3604f8e7b63c876c59d92642fb20 Mon Sep 17 00:00:00 2001 From: Alan West <3676547+alanwest@users.noreply.github.com> Date: Tue, 4 Feb 2025 17:17:43 -0800 Subject: [PATCH 2/4] Clean up --- ...opentelemetry-best-practices-resources.mdx | 60 ++++++++++++------- 1 file changed, 37 insertions(+), 23 deletions(-) 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 56a6321e815..9b3ea40b189 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,11 +122,17 @@ 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 infrastructure relationships using the OpenTelemetry Collector +### Service to infrastructure relationships using the OpenTelemetry Collector [#service-to-infra-otel-collector] -The following relationships between services and infrastructure are supported: +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] @@ -134,20 +140,28 @@ 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] -Entity relationships are supported between OpenTelemetry instrumented services -and infrastructure entities created by 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) +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 between services and infrastructure are supported: +The following relationships to your services are supported: * [Hosts](#service-to-infra-nr-infra-agent-hosts) * [Containers](#service-to-infra-nr-infra-agent-containers) @@ -157,22 +171,22 @@ The following relationships between services and infrastructure are supported: Host relationships between OpenTelemetry instrumented services and host entities generated from the New Relic infrastructure agent require two things: -1. The `host.id` resource attribute must be present on the telemetry from the - service. -2. The `host.id` must correlate with the host's identity derived by - the infrastructure agent. +* The `host.id` resource attribute must be present on the telemetry from the + service. +* The `host.id` must correlate with the host's 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 the following section -carefully to understand potential challenges. +hosts monitored with the infrastructure agent. Read this section carefully to +understand potential challenges. -##### Computing host identity - -The host identity computed by the New Relic infrastructure agent depends on +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 @@ -182,20 +196,20 @@ 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` +###### 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` 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 +###### 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 +###### 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 From 0d8df37d88144ada3f8fbff03e3628cd3b6b6b3f Mon Sep 17 00:00:00 2001 From: Alan West <3676547+alanwest@users.noreply.github.com> Date: Wed, 19 Feb 2025 10:39:57 -0800 Subject: [PATCH 3/4] Update src/content/docs/opentelemetry/best-practices/opentelemetry-best-practices-resources.mdx Co-authored-by: jack-berg <34418638+jack-berg@users.noreply.github.com> --- .../best-practices/opentelemetry-best-practices-resources.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) 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 9b3ea40b189..bc31c90d0ef 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 @@ -173,7 +173,7 @@ 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 derived by +* 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] From 4dcf5afa65cd31eddcfab11e688323fda068a2fd Mon Sep 17 00:00:00 2001 From: Alan West <3676547+alanwest@users.noreply.github.com> Date: Wed, 19 Feb 2025 10:45:30 -0800 Subject: [PATCH 4/4] Add links --- .../opentelemetry-best-practices-resources.mdx | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) 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 bc31c90d0ef..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 @@ -173,8 +173,8 @@ 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. +* 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] @@ -198,9 +198,10 @@ identity so that you can understand how to properly set the service's ###### 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` 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`. +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]