diff --git a/src/content/docs/opentelemetry/get-started/apm-monitoring/opentelemetry-apm-ui.mdx b/src/content/docs/opentelemetry/get-started/apm-monitoring/opentelemetry-apm-ui.mdx index 1fa7332ad1c..67c3e5e7259 100644 --- a/src/content/docs/opentelemetry/get-started/apm-monitoring/opentelemetry-apm-ui.mdx +++ b/src/content/docs/opentelemetry/get-started/apm-monitoring/opentelemetry-apm-ui.mdx @@ -28,42 +28,174 @@ redirects: - /docs/more-integrations/open-source-telemetry-integrations/opentelemetry/best-practices/opentelemetry-implementation-guide/ --- -The OpenTelemetry APM UI is a curated experience available for [service entities](/docs/opentelemetry/best-practices/opentelemetry-best-practices-resources/#services). If you haven't configured your service with New Relic and OpenTelemetry, see [OpenTelemetry APM monitoring](/docs/opentelemetry/get-started/apm-monitoring/opentelemetry-apm-intro/). +The APM experience is available for OpenTelemetry [service entities](/docs/opentelemetry/best-practices/opentelemetry-best-practices-resources/#services). +If you haven't configured your service with New Relic and OpenTelemetry, see +[OpenTelemetry APM monitoring](/docs/opentelemetry/get-started/apm-monitoring/opentelemetry-apm-intro/). -The OpenTelemetry APM UI pages are designed to help quickly identify and diagnose problems. Many require data to conform to various [OpenTelemetry semantic conventions](https://opentelemetry.io/docs/specs/semconv/), but some are general purpose. +## Find OpenTelemetry APM services [#find-apm-services] -The following New Relic concepts recur or have overlap across pages: +To find OpenTelemetry APM services, navigate to **All entities > Services - OpenTelemetry** +or **APM & Services**. Click on a service to navigate to the service's +[Summary page](#summary-page). -* [Golden signals](#golden-signals) -* [Narrow data with filters](#narrow-with-filters) -* [Metrics or spans toggle](#metrics-spans-toggle) +**TODO: How does filtering by entity tags work?** +Within the entity explorer, you can filter by [entity tags](/docs/new-relic-solutions/new-relic-one/core-concepts/use-tags-help-organize-find-your-data/). +For details on how entity tags are computed, see [OpenTelemetry resources in New Relic](/docs/opentelemetry/best-practices/opentelemetry-best-practices-resources). -## Find OpenTelemetry APM services [#find-apm-services] +## APM experience for OpenTelemetry + +OpenTelemetry instrumented services leverage the same curated APM experience as +services instrumented using New Relic's language agents. For this to work, +the OpenTelemetry data you send us is mapped to New Relic conventions. We do +this by generating the metrics required for driving the APM experience. These +generated metrics are directly sourced from your OpenTelemetry data. The +original OpenTelemetry data you've sent is ingested normally and remains +available for your custom dashboarding and alerting needs. + + +OpenTelemetry's semantic conventions continue to evolve as many of them are +not yet stable. Therefore, generating metrics normalized to New Relic +conventions reduces the burden on you to determine which version of the +OpenTelemetry conventions are emitted by the instrumentation you're using. + +For those who have used our APM language agents, another benefit is that you +can use the metrics and queries you're already familiar as you transition to +OpenTelemetry. + + +Understanding how OpenTelemetry data is mapped to New Relic conventions is +important for understanding how OpenTelemetry is supported by the APM +experience. + +OpenTelemetry data is comprised of metrics, spans, and logs. The APM experience +primarily leverages metric data because OpenTelemetry metrics provides an +accurate representation of the throughput, response time, and error rate of +your services. + + +Our older OpenTelemetry APM experience enabled you to view your data from the +perspective of either metric or span data. Viewing throughput, response time, +and error rate from the perspective of span data can be misleading due to +sampling. This experience is still available for you, but will be phased out +over time. See [Legacy span-based experience]() for more details. + + +**TODO: Move this callout and other span-synthesis scenarios to a dedicated section** + +OpenTelemetry supports metrics for most languages now, however Ruby is a +notable exception. For Ruby, we perform a best-faith effort to generate New +Relic metrics from span data. + + +The primary bodies of OpenTelemetry semantic conventions leveraged by the APM +experience are the [HTTP](https://opentelemetry.io/docs/specs/semconv/http/), +[RPC](https://opentelemetry.io/docs/specs/semconv/rpc/), +[messaging](https://opentelemetry.io/docs/specs/semconv/messaging/), +and [database](https://opentelemetry.io/docs/specs/semconv/database/) +conventions. + +### How transactions are derived from OpenTelemetry data [#transaction-mapping] + +New Relic’s APM experience is centered around the notion of a +[transaction](https://docs.newrelic.com/docs/apm/transactions/intro-transactions/transactions-new-relic-apm/). +When using a New Relic agent, it is the responsibility of the agent’s +instrumentation to define the scope of a transaction (e.g., a single web +request). The agent produces metric data that drives the vast majority of the +New Relic APM experience by recording transaction metrics measuring the +duration of transactions and its individual operations (e.g., external calls +and database calls). + +OpenTelemetry instrumentation does not have a direct analog to a New Relic +transaction, so adapting the notion of transactions to OpenTelemetry data is +key. + +By leveraging OpenTelemetry’s [semantic conventions](https://opentelemetry.io/docs/concepts/semantic-conventions/) +we can take advantage of OpenTelemetry’s highly structured and standardized +means of describing telemetry in order to drive the APM experience in a very +similar way to that of New Relic’s agents. + +The semantic conventions define standard metrics for measuring common +operations such as handling [HTTP](https://opentelemetry.io/docs/specs/semconv/http/http-metrics/) +or [RPC](https://opentelemetry.io/docs/specs/semconv/rpc/rpc-metrics/) +requests. These metrics are analogous to the transaction metrics that New Relic +agents produce for describing +[Web transactions](https://docs.newrelic.com/docs/apm/transactions/intro-transactions/transactions-new-relic-apm/#types). +We leverage OpenTelemetry’s HTTP and RPC metrics to synthesize metrics that +drive the APM UI such as the [`apm.service.transaction.duration` metric](#metric-apm-service-transaction-duration). + +New Relic also provides a notion of a +[non-web transaction](https://docs.newrelic.com/docs/apm/transactions/intro-transactions/monitor-background-processes-other-non-web-transactions/). +Non-web transactions are commonly used for systems that perform message +processing. Instrumentation that leverages OpenTelemetry’s [messaging conventions](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/messaging/messaging-spans.md) +will result in synthesizing metrics representing non-web transactions. + + +Do to the relative immaturity of OpenTelemetry's messaging conventions compared +to the HTTP and RPC conventions, we currently synthesize non-web transactions +for messaging operations from span data which follow the messaging conventions. + + +#### Transaction names -To find OpenTelemetry APM services, navigate to **All entities > Services > OpenTelemetry** or **APM & Services**. Click on a service to navigate to the service's [Summary page](#summary-page). +Each transaction has a name which is derived from attributes required by +OpenTelemetry’s semantic conventions. Refer to the [APM Service Metrics](#apm-service-metrics) +section for how this name is derived. -Within the entity explorer, you can filter by [entity tags](/docs/new-relic-solutions/new-relic-one/core-concepts/use-tags-help-organize-find-your-data/). For details on how entity tags are computed, see [OpenTelemetry resources in New Relic](/docs/opentelemetry/best-practices/opentelemetry-best-practices-resources). +##### Unknown transaction name -## Page: Summary [#summary-page] +Sometimes you may see a transaction with `unknown` in the name. This is an +indication that the source data used to derive the transaction does not follow +any of the established OpenTelemetry semantic conventions which we currently +support. -The summary page provides an overview of your service's health, including: +Some examples: -* **Golden signals**: response time, throughput, and error rate. See [Golden signals](#golden-signals) for details on how these are computed. -* **Related entities**: other services communicating with this service and related infrastructure. See [Service map](#service-map-page) for a detailed view. -* **Activity**: status of any alerts active for this service. -* **Distributed tracing insights**: discover whether downstream or upstream entities might be contributing to degraded performance. See [Related trace entity signals](/docs/distributed-tracing/ui-data/related-trace-entity-signals/) for more details. -* **Instances**: breakdown of golden signals by instance when a service is scaled horizontally. Depends on the `service.instance.id` resource attribute (see [Services](/docs/opentelemetry/best-practices/opentelemetry-best-practices-resources/#services) for more details). +* HTTP metrics missing `http.request.method` or `http.route`. For example, if the + `http.server.request.duration` metric is missing the `http.route` attribute + then the transaction name will be `WebTransaction/server/GET unknown`. +* Frameworks or protocols for which OpenTelemetry does not currently define + semantic conventions for (e.g., background jobs and CI frameworks). -## Page: Distributed tracing [#distributed-tracing-page] +## Navigating the APM experience -The distributed tracing page provides detailed insights into OpenTelemetry trace data. See [Distributed tracing](/docs/distributed-tracing/ui-data/understand-use-distributed-tracing-ui/) for page usage information. See [OpenTelemetry traces in New Relic](/docs/opentelemetry/best-practices/opentelemetry-best-practices-traces) for details on how OpenTelemetry trace data is ingested into New Relic. +### Summary [#summary-page] -As with [golden signals](#golden-signals), spans are classified as errors if the span status is set to `ERROR` (for example, `otel.status_code = ERROR`). If the span is an error, the span status description (for example, `otel.status_description`) is displayed in **error details**. +The [summary page](/docs/apm/agents/manage-apm-agents/agent-data/triage-run-diagnostics/) +provides an overview of your service's health and is centered around New +Relic's notion of a [transaction](/docs/apm/transactions/intro-transactions/transactions-new-relic-apm/). +See [How transactions are derived from OpenTelemetry data](#transaction-mapping) for more details. -OpenTelemetry span events attach additional event context information to a particular span. They are most commonly used to capture exception information. If available, you can view a span's events in **trace details**. +The New Relic metrics that drive the Summary page are the +[`apm.service.transaction.duration`](#metric-apm-service-transaction-duration) +and [`apm.service.error.count`](#metric-apm-service-error-count) +metrics. Refer to them for details on how they are derived from your +OpenTelemetry data. + +#### Customizing Apdex Target [#customizing-apdex-target] + +In New Relic instrumentation, custom apdex targets are configured using agent +configuration. For OpenTelemetry, when viewing a service navigate to +**Settings > Application** to configure your Apdex target. + +### Distributed tracing [#distributed-tracing-page] + +The distributed tracing page provides detailed insights into OpenTelemetry +trace data. See [Distributed tracing](/docs/distributed-tracing/ui-data/understand-use-distributed-tracing-ui/) +for page usage information. See [OpenTelemetry traces in New Relic](/docs/opentelemetry/best-practices/opentelemetry-best-practices-traces) +for details on how OpenTelemetry trace data is ingested into New Relic. + +As with [golden signals](#golden-signals), spans are classified as errors if +the span status is set to `ERROR` (for example, `otel.status_code = ERROR`). +If the span is an error, the span status description (for example, +`otel.status_description`) is displayed in **error details**. + +OpenTelemetry span events attach additional event context information to a +particular span. They are most commonly used to capture exception information. +If available, you can view a span's events in **trace details**. -The presence of a span exception event doesn't qualify the span as an error on its own. Only spans with span status set to `ERROR` are classified as errors. +The presence of a span exception event doesn't qualify the span as an error on +its own. Only spans with span status set to `ERROR` are classified as errors. -## Page: Service map [#service-map-page] +### Service map [#service-map-page] + +The service map page provides a visual representation of your entire +architecture. See [Service maps](/docs/new-relic-solutions/new-relic-one/ui-data/service-maps/service-maps/) +for more information. + +### Transactions [#transactions-page] + +The [transactions page](/docs/apm/apm-ui-pages/monitoring/transactions-page-find-specific-performance-problems/) +provides tools for identifying problems with and analyzing a service's +[transactions](/docs/apm/transactions/intro-transactions/transactions-new-relic-apm/#txn-defined). -The service map page provides a visual representation of your entire architecture. See [Service maps](/docs/new-relic-solutions/new-relic-one/ui-data/service-maps/service-maps/) for more information. +OpenTelemetry does not have a direct analog to New Relic's notion of a transaction. +See [How transactions are derived from OpenTelemetry data](#transaction-mapping) for more details. -## Page: Transactions [#transactions-page] +The New Relic metrics that drive the Transaction page are the +[`apm.service.transaction.duration`](#metric-apm-service-transaction-duration) +and [`apm.service.error.count`](#metric-apm-service-error-count) +metrics. Refer to them for details on how they are derived from your +OpenTelemetry data. -The transactions page provides tools for identifying problems with and analyzing a service's [transactions](/docs/apm/transactions/intro-transactions/transactions-new-relic-apm/#txn-defined). +For details on the New Relic metric that drives the Transaction page and how it +is derived from your OpenTelemetry data refer to the details of +the [`apm.service.transaction.duration`]() and [`apm.service.error.count`]() +metrics. -For metrics, the queries assume data conforms to the [HTTP metric](https://opentelemetry.io/docs/specs/semconv/http/http-metrics/) or [RPC metric](https://opentelemetry.io/docs/specs/semconv/rpc/rpc-metrics/) semantic conventions. The `http.route` and `rpc.method` attributes are used for listing and filtering by transaction. +#### Transaction traces -For spans, the queries are generic, utilizing only the top level span data model. Spans are counted towards transaction throughput and response time as described in [Golden signals](#golden-signals). The span name field is used for listing and filtering by transaction. +[Transaction traces](/docs/apm/transactions/transaction-traces/introduction-transaction-traces/) +for OpenTelemetry are derived from your span data. On the transactions page you +can find a list of transaction traces. This list requires the span data +and metric data for a given transaction be correlated together. We do this by +adding a `transaction.name` attribute to the root span of a transaction trace. -## Page: Databases [#databases-page] +#### Segment breakdown [#segment-breakdown] -The databases page provides tools for identifying problems with and analyzing a service's database client operations. +Clicking on a transaction opens a detailed view of the transaction revealing a +segment breakdown. Unlike New Relic agents, OpenTelemetry does not emit metrics +for individual segments. Therefore, the New Relic metrics required for driving +the segment breakdown are derived from span data. -There is no metrics-based view of databases since there are currently no semantic conventions available. +The notable downside to computing segment breakdown from span data is that +spans are usually sampled. Though, even with sampling, the segment breakdown +can still serve to help you identify specific methods or operations that +consume the most time within a transaction. -For spans, the queries assume data conforms to the [DB span](https://opentelemetry.io/docs/specs/semconv/database/database-spans/) semantic conventions. The span name, and `db.system`, `db.sql.table`, and `db.operation` attributes are used for listing and filtering database operations. +From span data, we estimate a sampling rate by computing a throughput based on +span data received and divide that by the actual throughput as reported by your +metric data. The estimated sampling rate enables us to extrapolate the segment +breakdown of a transaction. -## Page: External services [#externals-page] +This process is not perfect and can be affected by a number of factors, most +notably your sampling strategy. It works best when you're strictly sampling +a percentage of your span data. However, for example, if you sample only +spans representing errors, then the segment breakdown may be skewed. + +### Databases [#databases-page] + +The databases page provides tools for identifying problems with and analyzing a +service's database client operations. + +OpenTelemetry instrumentation represents calls to databases using the +[database](https://opentelemetry.io/docs/specs/semconv/database/) +semantic conventions. + +The New Relic metric that drives the databases page is the +[`apm.service.datastore.operation.duration`](#metric-apm-service-datastore-operation-duration) +metric. Refer to it for details on how it is derived from your +OpenTelemetry data. + +#### Time consumption by caller + +When you click on a specific database call, you will see the +"Time consumption by caller" chart. This chart is driven by the +[`apm.service.transaction.overview`](#metric-apm-service-transaction-overview) metric. +This is the same metric that drives the [segment breakdown](#segment-breakdown) +view of the transaction page and it is derived from span data. + + +OpenTelemetry's database semantic conventions were recently deemed stable. +There does not yet exist many stable instrumentations, and the instrumentation +that does exist often only emits span data and no metric data. + +As such, when using instrumentation that has not yet adopted the stable +semantic conventions, the APM metrics generated driving the database page are +derived from span data. + +As stable instrumentation becomes available and you adopt it, the database page +will begin to leverage OpenTelemetry metric data. Reach out to the OpenTelemetry +community regarding the availability of stable database instrumentation in your +language. + -The externals page provides tools for identifying problems with and analyzing a service's external calls, including calling entities (upstream services) and called entities (downstream services). +### External services [#externals-page] -There is no metrics-based view of the external services page. +The [external services page](/docs/apm/apm-ui-pages/monitoring/external-services/external-services-ui/) +provides tools for identifying problems with and analyzing a service's external +calls, including calling entities (upstream services) and called entities +(downstream services). -For spans, the queries are generic, utilizing only the top level span data model. Spans are counted towards external service throughput and response time if they are exiting a service, computed using a heuristic of `WHERE span.kind = client OR span.kind = producer`. Database client spans are filtered out using `WHERE db.system is null` (see [Page: Databases](#databases-page)). As with [golden signals](#golden-signals), spans are errors if they have a status code of `ERROR` (for example, `otel.status_code = ERROR`). If available, data from the [HTTP span](https://opentelemetry.io/docs/specs/semconv/http/http-spans/) and [RPC span](https://opentelemetry.io/docs/specs/semconv/rpc/rpc-spans/) semantic conventions are used to classify external service calls. +OpenTelemetry instrumentation represents calls to external services using the +[HTTP](https://opentelemetry.io/docs/specs/semconv/http/) and [RPC](https://opentelemetry.io/docs/specs/semconv/rpc/) +semantic conventions. -## Page: JVM runtime [#jvm-runtime-page] +The New Relic metric that drives the databases page is the +[`apm.service.external.host.duration`]() +metric. Refer to it for details on how it is derived from your +OpenTelemetry data. -The JVM runtime page provides tools for identifying problems with and analyzing a Java service's JVM. The page is only displayed for services using [OpenTelemetry java](https://opentelemetry.io/docs/languages/java/). In order to differentiate between distinct service instances, the page requires the `service.instance.id` resource attribute to be set (see [Services](/docs/opentelemetry/best-practices/opentelemetry-best-practices-resources/#services) for more details). +#### Time consumption by caller -The JVM runtime page shows golden signals alongside JVM runtime metrics to correlate runtime issues with service usage. The [metrics or spans toggle](#metrics-spans-toggle) dictates whether the [golden signals](#golden-signals) are driven by span or metric data. There is no spans-based view for JVM runtime metrics. +When you click on a specific external call, you will see the +"Time consumption by caller" chart. This chart is driven by the +[`apm.service.transaction.overview`](#metric-apm-service-transaction-overview) metric. +This is the same metric that drives the [segment breakdown](#segment-breakdown) +view of the transaction page and it is derived from span data. -For metrics, the queries assume data conforms to the [JVM metric](https://opentelemetry.io/docs/specs/semconv/runtime/jvm-metrics/) semantic conventions. Note, these conventions are embodied in [OpenTelemetry Java runtime instrumentation library](https://github.com/open-telemetry/opentelemetry-java-instrumentation/tree/main/instrumentation/runtime-telemetry/runtime-telemetry-java8/library), which is automatically included with the OpenTelemetry java agent. +### JVM runtime [#jvm-runtime-page] -## Page: Go runtime [#go-runtime-page] +The JVM runtime page provides tools for identifying problems with and analyzing +a Java service's JVM. The page is only displayed for services using [OpenTelemetry Java](https://opentelemetry.io/docs/languages/java/). +In order to differentiate between distinct service instances, the page requires +the `service.instance.id` resource attribute to be set (see +[Services](/docs/opentelemetry/best-practices/opentelemetry-best-practices-resources/#services) +for more details). -The Go runtime page provides tools for identifying problems with and analyzing a Go service's runtime. The page is only displayed for services using [OpenTelemetry Go](https://opentelemetry.io/docs/languages/go/). In order to differentiate between distinct service instances, the page requires the `service.instance.id` resource attribute to be set (see [Services](/docs/opentelemetry/best-practices/opentelemetry-best-practices-resources/#services) for more details). +The JVM runtime page shows golden signals alongside JVM runtime metrics to +correlate runtime issues with service usage. -The Go runtime page shows golden signals alongside Go runtime metrics to correlate runtime issues with service usage. The [metrics or spans toggle](#metrics-spans-toggle) dictates whether the [golden signals](#golden-signals) are driven by span or metric data. There is no spans-based view for Go runtime metrics. +The queries assume data conforms to the [JVM metric](https://opentelemetry.io/docs/specs/semconv/runtime/jvm-metrics/) +semantic conventions. Note, these conventions are embodied in +[OpenTelemetry Java runtime instrumentation library](https://github.com/open-telemetry/opentelemetry-java-instrumentation/tree/main/instrumentation/runtime-telemetry/runtime-telemetry-java8/library), +which is automatically included with the OpenTelemetry java agent. -For metrics, the queries assume data is produced by the [OpenTelemetry Go runtime instrumentation library](https://github.com/open-telemetry/opentelemetry-go-contrib/tree/main/instrumentation/runtime). Note, there are currently no semantic conventions for Go runtime metrics. +### Go runtime [#go-runtime-page] -## Page: Logs [#logs-page] +The Go runtime page provides tools for identifying problems with and analyzing +a Go service's runtime. The page is only displayed for services using [OpenTelemetry Go](https://opentelemetry.io/docs/languages/go/). +In order to differentiate between distinct service instances, the page requires +the `service.instance.id` resource attribute to be set (see [Services](/docs/opentelemetry/best-practices/opentelemetry-best-practices-resources/#services) +for more details). -The Logs page provides tools for identifying problems and analyzing a service's logs. See [Use logs UI](/docs/logs/ui-data/use-logs-ui/) for more information. +The Go runtime page shows golden signals alongside Go runtime metrics to +correlate runtime issues with service usage. -## Page: Errors inbox [#errors-inbox-page] +The queries assume data is produced by the [OpenTelemetry Go runtime instrumentation library](https://github.com/open-telemetry/opentelemetry-go-contrib/tree/main/instrumentation/runtime). +Note, there are currently no semantic conventions for Go runtime metrics. -The errors inbox page provides tools for detecting and triaging a service's errors. See [Getting started with errors inbox](/docs/errors-inbox/getting-started/) for more details. +### Logs [#logs-page] -The errors inbox page is driven by trace deta. As with [golden signals](#golden-signals), spans are classified as errors if the span status is set to `ERROR` (for example, `otel.status_code = ERROR`). +The Logs page provides tools for identifying problems and analyzing a service's +logs. See [Use logs UI](/docs/logs/ui-data/use-logs-ui/) for more information. -Error spans are grouped together by their error fingerprint, computed by normalizing away identifying values such as UUIDs, hex values, email addresses, etc. Each distinct error span is an individual instance within the error group. The error group message is determined as follows: +### Errors inbox [#errors-inbox-page] + +The errors inbox page provides tools for detecting and triaging a service's +errors. See [Getting started with errors inbox](/docs/errors-inbox/getting-started/) +for more details. + +The errors inbox page is driven by trace data. As with [golden signals](#golden-signals), +spans are classified as errors if the span status is set to `ERROR` (for +example, `otel.status_code = ERROR`). + +Error spans are grouped together by their error fingerprint, computed by +normalizing away identifying values such as UUIDs, hex values, email addresses, +etc. Each distinct error span is an individual instance within the error group. +The error group message is determined as follows: * Span status description (for example, `otel.status_description`) * `rpc.grpc.status_code` from [RPC span](https://opentelemetry.io/docs/specs/semconv/rpc/rpc-spans/) semantic conventions @@ -134,9 +378,133 @@ Error spans are grouped together by their error fingerprint, computed by normali * `http.response.status_code` from [HTTP span](https://opentelemetry.io/docs/specs/semconv/http/http-spans/) semantic conventions * `undefined` if none of the above are present -## Page: Metrics explorer [#metrics-explorer-page] +## APM Service Metrics + +The apm.service.\* metrics drive New Relic’s APM experience. The following +describes the source OpenTelemetry data that is used to derive the +corresponding apm.service.\* metrics. + +## Metric resource attributes + +The following resource attributes are copied from source data on to APM metrics: + +* `container.id` +* `entity.guid` +* `host.name` +* `instrumentation.provider` +* `k8s.cluster.name` +* `k8s.container.name` +* `k8s.namespace.name` +* `k8s.pod.name` +* `service.instance.id` +* `service.name` + +## Metric: `apm.service.transaction.duration` + +| Name | [Instrument Type](https://docs.newrelic.com/docs/data-apis/understand-data/metric-data/metric-data-type/) | Unit ([UCUM](https://ucum.org/ucum)) | Description | +|---|---|---|---| +| `apm.service.transaction.duration` | Distribution | `s`, `ms`, `ns` **[1]** | Duration of transactions. **[2]** | + +| Attribute | Type | Description | Example | +|---|---|---|---| +| `transactionName` | `string` | The name of the transaction. | `WebTransaction/server/GET /users/:id`,`OtherTransaction/consumer/unknown` | +| `transactionType` | `string` | The type of the transaction. | `Web`,`Other` | +| `error.type` | `string` | Describes a class of error the transaction ended with. | `500`,`TimeoutException` | + +**[1]**: Unit from source metric is copied. + +**[2]**: If `error.type` resolves to non-null, `apm.service.error.count` is incremented with the respective count of the source data. + +### Metric sources + +| Semantic Convention | Metric name | Conditions | `transactionName` | `transactionType` | `error.type` | +|---|---|---|---|---|---| +| [`OtelHttpServer1_23`](https://github.com/open-telemetry/semantic-conventions/blob/v1.23.0/docs/http/http-metrics.md) | `http.server.request.duration` | `http.request.method IS NOT NULL` | `WebTransaction/server/${http.request.method} ${http.route}` | `Web` | `${error.type}` | +| [`OtelHttpServer1_20`](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.20.0/specification/metrics/semantic_conventions/http-metrics.md) | `http.server.duration` | `http.method IS NOT NULL` | `WebTransaction/server/${http.method} ${http.route}` | `Web` | `__http_error_status_code_or_null__` | +| [`OtelRpcServer1_20`](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.20.0/specification/trace/semantic_conventions/rpc.md) | `rpc.server.duration` | `rpc.system IS NOT NULL` | `WebTransaction/server/${rpc.system}/${rpc.service:-unknown}.${rpc.method:-unknown}` | `Web` | `__rpc_error_status_code_or_null__` | + +## Metric: `apm.service.transaction.overview` + +| Name | [Instrument Type](https://docs.newrelic.com/docs/data-apis/understand-data/metric-data/metric-data-type/) | Unit ([UCUM](https://ucum.org/ucum)) | Description | +|---|---|---|---| +| `apm.service.transaction.overview` | Summary | s | Segment breakdown time of a transaction. | + +| Attribute | Type | Description | Example | +|---|---|---|---| +| `transactionName` | `string` | The name of the transaction. | `WebTransaction/server/GET /users/:id`,`OtherTransaction/consumer/unknown` | +| `transactionType` | `string` | The type of the transaction. | `Web`,`Other` | +| `db.system` | `string` | The database management system (DBMS) product as identified by the client instrumentation. | `postgresql`,`mysql`,`mariadb` | +| `db.sql.table` | `string` | The name of a collection (table, container) within the database. | `public.users`,`customers` | +| `db.operation` | `string` | The name of the operation or command being executed. | `findAndModify`,`HMSET`,`SELECT` | +| `external.host` | `string` | Server domain if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name | `example.com`,`10.1.2.80`,`/tmp/my.sock` | + +### Span sources -The Metrics explorer provides tools for exploring a service's metrics in a generic manner. See [Explore your data](/docs/query-your-data/explore-query-data/browse-data/introduction-data-explorer/#explore-data) for more information. +| Semantic Convention | Span kind | Conditions | `transactionName` | `transactionType` | `db.system` | `db.sql.table` | `db.operation` | `external.host` | +|---|---|---|---|---|---|---|---|---| +| [`OtelHttpServer1_23`](https://github.com/open-telemetry/semantic-conventions/blob/v1.23.0/docs/http/http-metrics.md) | `server` | `http.request.method IS NOT NULL` | `WebTransaction/server/${http.request.method} ${http.route}` | `Web` | | | | | +| [`OtelHttpServer1_20`](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.20.0/specification/metrics/semantic_conventions/http-metrics.md) | `server` | `http.method IS NOT NULL` | `WebTransaction/server/${http.method} ${http.route}` | `Web` | | | | | +| [`OtelRpcServer1_20`](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.20.0/specification/trace/semantic_conventions/rpc.md) | `server` | `rpc.system IS NOT NULL` | `WebTransaction/server/${rpc.system}/${rpc.service:-unknown}.${rpc.method:-unknown}` | `Web` | | | | | +| [`OtelMessagingConsumer1_24`](https://github.com/open-telemetry/semantic-conventions/blob/v1.24.0/docs/messaging/messaging-spans.md) | `consumer` | `messaging.operation IS NOT NULL` | `OtherTransaction/consumer/${messaging.operation:-unknown}/${messaging.destination.template:-${messaging.destination.name:-unknown}}` | `Other` | | | | | +| [`OtelDbClient1_33`](https://github.com/open-telemetry/semantic-conventions/blob/v1.33.0/docs/database/database-metrics.md) | `internal`
`client` | `db.system.name IS NOT NULL` | `transactionName` of the local root span | `transactionType` of the local root span | `${db.system.name}` | `${db.stored_procedure.name:-${db.collection.name:-${__db_summary_to_sql_table__}}}` | `${db.operation.name:-${__db_summary_to_operation__:-unknown}}` | | +| [`OtelDbClientRedis1_24`](https://github.com/open-telemetry/semantic-conventions/blob/v1.24.0/docs/database/database-spans.md) | `client` | `db.system IS NOT NULL`
`db.system = 'redis'` | `transactionName` of the local root span | `transactionType` of the local root span | `${db.system}` | `${db.sql.table}` | `${name:-unknown}` | | +| [`OtelDbClient1_24`](https://github.com/open-telemetry/semantic-conventions/blob/v1.24.0/docs/database/database-spans.md) | `client` | `db.system IS NOT NULL` | `transactionName` of the local root span | `transactionType` of the local root span | `${db.system}` | `${db.sql.table}` | `${db.operation:-unknown}` | | +| [`OtelHttpClient1_23`](https://github.com/open-telemetry/semantic-conventions/blob/v1.23.1/docs/http/http-metrics.md) | `client` | `http.request.method IS NOT NULL` | `transactionName` of the local root span | `transactionType` of the local root span | | | | `${server.address:-unknown}` | +| [`OtelHttpClient1_20`](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.20.0/specification/metrics/semantic_conventions/http-metrics.md) | `client` | `http.method IS NOT NULL` | `transactionName` of the local root span | `transactionType` of the local root span | | | | `${net.peer.name:-unknown}` | +| [`OtelRpcClient1_20`](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.20.0/specification/metrics/semantic_conventions/rpc-metrics.md) | `client` | `rpc.system IS NOT NULL` | `transactionName` of the local root span | `transactionType` of the local root span | | | | `${net.peer.name:-unknown}` | + +## Metric: `apm.service.external.host.duration` + +| Name | [Instrument Type](https://docs.newrelic.com/docs/data-apis/understand-data/metric-data/metric-data-type/) | Unit ([UCUM](https://ucum.org/ucum)) | Description | +|---|---|---|---| +| `apm.service.external.host.duration` | Distribution | `s`, `ms`, `ns` **[1]** | Duration of external calls. | + +| Attribute | Type | Description | Example | +|---|---|---|---| +| `external.host` | `string` | Server domain if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name | `example.com`,`10.1.2.80`,`/tmp/my.sock` | + +**[1]**: Unit from source metric is copied. + +### Metric sources + +| Semantic Convention | Metric name | Conditions | `external.host` | +|---|---|---|---| +| [`OtelHttpClient1_23`](https://github.com/open-telemetry/semantic-conventions/blob/v1.23.1/docs/http/http-metrics.md) | `http.client.request.duration` | `http.request.method IS NOT NULL` | `${server.address:-unknown}` | +| [`OtelHttpClient1_20`](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.20.0/specification/metrics/semantic_conventions/http-metrics.md) | `http.client.duration` | `http.method IS NOT NULL` | `${net.peer.name:-unknown}` | +| [`OtelRpcClient1_20`](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.20.0/specification/metrics/semantic_conventions/rpc-metrics.md) | `rpc.client.duration` | `rpc.system IS NOT NULL` | `${net.peer.name:-unknown}` | + +## Metric: `apm.service.datastore.operation.duration` + +| Name | [Instrument Type](https://docs.newrelic.com/docs/data-apis/understand-data/metric-data/metric-data-type/) | Unit ([UCUM](https://ucum.org/ucum)) | Description | +|---|---|---|---| +| `apm.service.datastore.operation.duration` | Distribution | `s`, `ms`, `ns` **[1]** | Duration of datastore calls. | + +| Attribute | Type | Description | Example | +|---|---|---|---| +| `db.system` | `string` | The database management system (DBMS) product as identified by the client instrumentation. | `postgresql`,`mysql`,`mariadb` | +| `db.sql.table` | `string` | The name of a collection (table, container) within the database. | `public.users`,`customers` | +| `db.operation` | `string` | The name of the operation or command being executed. | `findAndModify`,`HMSET`,`SELECT` | +| `db.query.summary` | `string` | Low cardinality summary of a database query. | `SELECT wuser_table`,`INSERT shipping_details`,`SELECT order` | + +**[1]**: Unit from source metric is copied. + +### Metric sources + +| Semantic Convention | Metric name | Conditions | `db.system` | `db.sql.table` | `db.operation` | `db.query.summary` | +|---|---|---|---|---|---|---| +| [`OtelDbClient1_33`](https://github.com/open-telemetry/semantic-conventions/blob/v1.33.0/docs/database/database-metrics.md) | `db.client.operation.duration` | `db.system.name IS NOT NULL` | `${db.system.name}` | `${db.stored_procedure.name:-${db.collection.name:-${__db_summary_to_sql_table__}}}` | `${db.operation.name:-${__db_summary_to_operation__:-unknown}}` | `${db.query.summary}` | + +## Helper functions + +Helper functions are references to bits of attribute mapping logic which are more involved than simple attribute references. + +| Function | Description | +|---|---| +| `__http_error_status_code_or_null__` | Returns string value of `http.status_code if >= 500` | +| `__rpc_error_status_code_or_null__` | Returns string value of rpc.grpc.status_code if in set: `[2,4,12,13,14,15]` | +| `__db_summary_to_operation__` | Returns first word in `db.query.summary` in set (case insensitive): `[alter,call,create,delete,drop,exec,execute,insert,merge,select,set,update]` | +| `__db_summary_to_sql_table__` | Returns first word in `db.query.summary` NOT in set (case insensitive): `[alter,call,create,delete,drop,exec,execute,insert,merge,select,set,update]` | +| `__null__` | Placeholder for `null` | ## Golden signals [#golden-signals] @@ -150,14 +518,6 @@ For spans, the queries are generic, utilizing only the top level span data model Several pages include a filter bar, with options like **Narrow data to...**. This allows you to filter queries on the page to match the criteria. For example, you might narrow to a particular canary deployment by filtering for `service.version='1.2.3-canary'`. Filters are preserved when navigating between pages. -## Metrics or spans toggle [#metrics-spans-toggle] - -Various pages include a metrics or spans toggle. This allows you to choose whether queries are driven by span or metric data based on analysis requirements and data availability. - -Metrics are not subject to sampling, and are thus more accurate, especially when computing rates like throughput. However, metrics are subject to cardinality constraints, and may lack certain attributes important for analysis. In contrast, spans are sampled and thus subject to accuracy issues, but have richer attributes since they are not subject to cardinality constraints. - -Historically, OpenTelemetry language APIs and SDKs and instrumentation prioritized trace instrumentation. However, the project has come a long way and metrics are available in almost all languages. Check the [documentation](https://opentelemetry.io/docs/languages/) of the relevant language and instrumentation for more details. - ## Golden metrics Golden metrics are low-cardinality versions of golden signals data, such as HTTP/RPC metrics. They populate various platform experiences, including the Entity Explorer, Workloads Activity page, and Change Tracking Details page. These metrics use names like `newrelic.goldenmetrics.ext.service.*`.