adobe · iivvaannxx · Aug 6, 2025 · Aug 4, 2025
@@ -76,34 +76,34 @@ import {
 | [EntrypointInstrumentationConfig](interfaces/EntrypointInstrumentationConfig.md) | The configuration for entrypoint instrumentation.                                 |
 | [InstrumentationConfig](interfaces/InstrumentationConfig.md)                     | The configuration for instrumentation.                                            |
 | [InstrumentationContext](interfaces/InstrumentationContext.md)                   | The context for the current operation.                                            |
-| [TelemetryApi](interfaces/TelemetryApi.md)                                       | Defines the global telemetry API. These items should be set once per-application. |
+| [TelemetryApi](interfaces/TelemetryApi.md)                                       | Defines the global telemetry API. These items should be set once per application. |
 | [TelemetryConfig](interfaces/TelemetryConfig.md)                                 | The configuration options for the telemetry module.                               |
 | [TelemetryDiagnosticsConfig](interfaces/TelemetryDiagnosticsConfig.md)           | The configuration for the telemetry diagnostics.                                  |
 | [TelemetryPropagationConfig](interfaces/TelemetryPropagationConfig.md)           | Configuration related to context propagation (for distributed tracing).           |
 
 ## Type Aliases
 
-| Type Alias                                                                       | Description                                             |
-| -------------------------------------------------------------------------------- | ------------------------------------------------------- |
-| [DiagnosticsLogLevel](type-aliases/DiagnosticsLogLevel.md)                       | Available log levels for the OpenTelemetry DiagLogger.  |
-| [TelemetryInstrumentationPreset](type-aliases/TelemetryInstrumentationPreset.md) | Defines the names of available instrumentation presets. |
+| Type Alias                                                                       | Description                                              |
+| -------------------------------------------------------------------------------- | -------------------------------------------------------- |
+| [DiagnosticsLogLevel](type-aliases/DiagnosticsLogLevel.md)                       | Available log levels for the OpenTelemetry `DiagLogger`. |
+| [TelemetryInstrumentationPreset](type-aliases/TelemetryInstrumentationPreset.md) | Defines the names of available instrumentation presets.  |
 
 ## Functions
 
 | Function                                                                                | Description                                                                                                                                                                                                                                    |
 | --------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | [addEventToActiveSpan](functions/addEventToActiveSpan.md)                               | Adds an event to the given span.                                                                                                                                                                                                               |
 | [defineMetrics](functions/defineMetrics.md)                                             | Helper to define a record of metrics.                                                                                                                                                                                                          |
-| [defineTelemetryConfig](functions/defineTelemetryConfig.md)                             | Helper to define the telemetry config for an entrypoint.                                                                                                                                                                                       |
+| [defineTelemetryConfig](functions/defineTelemetryConfig.md)                             | Helper to define the telemetry configuration for an entrypoint.                                                                                                                                                                                |
 | [deserializeContextFromCarrier](functions/deserializeContextFromCarrier.md)             | Deserializes the context from a carrier and augments the given base context with it.                                                                                                                                                           |
 | [getActiveSpan](functions/getActiveSpan.md)                                             | Gets the active span from the given context.                                                                                                                                                                                                   |
 | [getAioRuntimeAttributes](functions/getAioRuntimeAttributes.md)                         | Infers some useful attributes for the current action from the Adobe I/O Runtime and returns them as a record of key-value pairs.                                                                                                               |
 | [getAioRuntimeResource](functions/getAioRuntimeResource.md)                             | Creates a [resource](https://open-telemetry.github.io/opentelemetry-js/interfaces/_opentelemetry_sdk-node.resources.Resource.html) from the attributes inferred from the Adobe I/O Runtime and returns it as an OpenTelemetry Resource object. |
 | [getAioRuntimeResourceWithAttributes](functions/getAioRuntimeResourceWithAttributes.md) | Creates a [resource](https://open-telemetry.github.io/opentelemetry-js/interfaces/_opentelemetry_sdk-node.resources.Resource.html) that combines the attributes inferred from the Adobe I/O Runtime with the provided attributes.              |
 | [getGlobalTelemetryApi](functions/getGlobalTelemetryApi.md)                             | Gets the global telemetry API.                                                                                                                                                                                                                 |
 | [getInstrumentationHelpers](functions/getInstrumentationHelpers.md)                     | Access helpers for the current instrumented operation.                                                                                                                                                                                         |
-| [getLogger](functions/getLogger.md)                                                     | Get a logger instance.                                                                                                                                                                                                                         |
-| [getPresetInstrumentations](functions/getPresetInstrumentations.md)                     | Get the instrumentations for a given preset.                                                                                                                                                                                                   |
+| [getLogger](functions/getLogger.md)                                                     | Gets a logger instance that can export OpenTelemetry logs.                                                                                                                                                                                     |
+| [getPresetInstrumentations](functions/getPresetInstrumentations.md)                     | Gets the instrumentations for a given preset.                                                                                                                                                                                                  |
 | [instrument](functions/instrument.md)                                                   | Instruments a function.                                                                                                                                                                                                                        |
 | [instrumentEntrypoint](functions/instrumentEntrypoint.md)                               | Instruments the entrypoint of a runtime action. Needs to be used ONLY with the `main` function of a runtime action.                                                                                                                            |
 | [serializeContextIntoCarrier](functions/serializeContextIntoCarrier.md)                 | Serializes the current context into a carrier.                                                                                                                                                                                                 |

@@ -16,7 +16,7 @@ function defineTelemetryConfig(
 
 Defined in: [core/config.ts:25](https://github.com/adobe/aio-lib-telemetry/blob/dd348342643b2b66d5a8c5267221de639b83642e/source/core/config.ts#L25)
 
-Helper to define the telemetry config for an entrypoint.
+Helper to define the telemetry configuration for an entrypoint.
 
 ## Parameters
 

@@ -6,7 +6,7 @@ function getLogger(name: string, config?: AioLoggerConfig): AioLogger;
 
 Defined in: [core/logging.ts:83](https://github.com/adobe/aio-lib-telemetry/blob/dd348342643b2b66d5a8c5267221de639b83642e/source/core/logging.ts#L83)
 
-Get a logger instance.
+Gets a logger instance that can export OpenTelemetry logs.
 
 ## Parameters
 

@@ -15,7 +15,7 @@ function getPresetInstrumentations(
 
 Defined in: [api/presets.ts:52](https://github.com/adobe/aio-lib-telemetry/blob/dd348342643b2b66d5a8c5267221de639b83642e/source/api/presets.ts#L52)
 
-Get the instrumentations for a given preset.
+Gets the instrumentations for a given preset.
 
 ## Parameters
 

@@ -2,7 +2,7 @@
 
 Defined in: [types.ts:189](https://github.com/adobe/aio-lib-telemetry/blob/dd348342643b2b66d5a8c5267221de639b83642e/source/types.ts#L189)
 
-Defines the global telemetry API. These items should be set once per-application.
+Defines the global telemetry API. These items should be set once per application.
 
 ## Since
 

@@ -6,7 +6,7 @@ type DiagnosticsLogLevel = Lowercase<keyof typeof DiagLogLevel>;
 
 Defined in: [types.ts:32](https://github.com/adobe/aio-lib-telemetry/blob/dd348342643b2b66d5a8c5267221de639b83642e/source/types.ts#L32)
 
-Available log levels for the OpenTelemetry DiagLogger.
+Available log levels for the OpenTelemetry `DiagLogger`.
 
 ## Since
 

@@ -63,10 +63,14 @@ The library is designed to configure OpenTelemetry on a **per-action basis**, bu
 
 ### Open Telemetry Configuration
 
-There are 2 different ways to configure Open Telemetry in Node.js:
+There are two ways to configure Open Telemetry in Node.js:
 
-- [Using environment variables](https://opentelemetry.io/docs/languages/sdk-configuration/) (currently not supported)
 - At runtime, via the [Node SDK configuration](https://open-telemetry.github.io/opentelemetry-js/modules/_opentelemetry_sdk-node.html#configuration) object
+- [Using environment variables](https://opentelemetry.io/docs/languages/sdk-configuration/) (currently not supported)
+
+#### Node SDK Configuration
+
+This is the currently supported method for configuring OpenTelemetry with this library. You'll need to provide a NodeSDK configuration object that will be passed directly to the `NodeSDK` constructor. For detailed information about each configuration option, please refer to the [official OpenTelemetry documentation](https://opentelemetry.io/docs/languages/js/instrumentation/#initialize-the-sdk).
 
 #### Environment Variables
 
@@ -77,10 +81,6 @@ When searching for OpenTelemetry usage examples, you'll find numerous tutorials
 
 However, these variables need to be present in `process.env`, and due to how App Builder handles environment variables (fed via `params`), this configuration method is currently not supported.
 
-#### Node SDK Configuration
-
-This is the currently supported method for configuring OpenTelemetry with this library. You'll need to provide a NodeSDK configuration object that will be passed directly to the `NodeSDK` constructor. For detailed information about each configuration option, please refer to the [official OpenTelemetry documentation](https://opentelemetry.io/docs/languages/js/instrumentation/#initialize-the-sdk).
-
 ### Writing your Telemetry Configuration
 
 Before you start using this library you need to configure it.

@@ -16,7 +16,7 @@ Below is a summary table of the documented use cases. Key terms:
 - `Local Development`: Runtime actions executed locally using `aio app dev`
 
 - `In Cloud`: Runtime actions deployed to the cloud via `aio app deploy`
-  - A `Via Tunneling` indicator shows that the guide demonstrates forwarding telemetry from deployed actions to a local observability stack. This is just one possible approach, you're not required to use tunneling (especially not in production). For instance, with hosted solutions like Grafana, you can configure direct data transmission instead.
+  - A `Via Tunneling` indicator shows that the guide demonstrates forwarding telemetry from deployed actions to a local observability stack. This is just one possible approach. You're not required to use tunneling (especially not in production). For instance, with hosted solutions like Grafana, you can configure direct data transmission instead.
 
 <table>
   <thead>

@@ -14,23 +14,14 @@ This guide demonstrates how to configure Grafana with App Builder runtime action
 - [OpenTelemetry Instrumentation with Grafana](#opentelemetry-instrumentation-with-grafana)
   - [Prerequisites](#prerequisites)
   - [Local Development](#local-development)
-    - [Setup](#setup)
-    - [Docker Compose Configuration](#docker-compose-configuration)
-    - [OpenTelemetry Collector Configuration](#opentelemetry-collector-configuration)
-    - [Tempo Configuration](#tempo-configuration)
-    - [Prometheus Configuration](#prometheus-configuration)
-    - [Telemetry Configuration](#telemetry-configuration)
-    - [Visualize the Data](#visualize-the-data)
+  - [Visualize the Data](#visualize-the-data)
   - [App Builder](#app-builder)
-    - [Tunneling Setup](#tunneling-setup)
-    - [Updated Telemetry Configuration](#updated-telemetry-configuration)
 
 ## Prerequisites
 
 - Docker and Docker Compose
 - An App Builder project with OpenTelemetry instrumentation.
-- A tunneling tool for App Builder (see [Tunneling Guide](../support/tunnel-forwarding.md) for setup instructions).
-  - We'll be using Cloudflare Tunnel (cloudflared) for this example.
+- A tunneling tool for App Builder (see [Tunneling Guide](../support/tunnel-forwarding.md) for setup instructions). We'll be using Cloudflare Tunnel (cloudflared) for this example.
 
 ## Local Development
 

@@ -11,12 +11,7 @@ This guide demonstrates how to configure runtime actions to send telemetry signa
 - [OpenTelemetry Instrumentation with New Relic](#opentelemetry-instrumentation-with-new-relic)
   - [Prerequisites](#prerequisites)
   - [Setup](#setup)
-    - [Configuration](#configuration)
-    - [How to Use](#how-to-use)
   - [Visualize the Data](#visualize-the-data)
-    - [Traces](#traces)
-    - [Metrics](#metrics)
-    - [Logs](#logs)
 
 ## Prerequisites
 
@@ -127,7 +122,7 @@ export const telemetryConfig = defineTelemetryConfig((params, isDev) => {
 
 ### How to Use
 
-Exporting directly to New Relic will seamlessly work in both development and production environments (no configuration changes required). Follow the [library documentation](../../README.md#-how-to-use) to instrument your runtime actions.
+Exporting directly to New Relic works in both development and production environments (no configuration changes required). Follow the [library documentation](../../README.md#-how-to-use) to instrument your runtime actions.
 
 ## Visualize the Data
 

@@ -173,7 +173,7 @@ my-action:
 > [!NOTE]
 > For most development scenarios, HTTP tunneling is sufficient and simpler to set up. Consider gRPC only if you're experiencing performance issues or need to test gRPC-specific functionality.
 
-OpenTelemetry supports both HTTP and gRPC protocols for OTLP (OpenTelemetry Protocol). While HTTP works with all tunneling tools, **gRPC requires TCP tunneling support**, which is only available with ngrok. For gRPC tunneling use just the base endpoint without path suffixes:
+OpenTelemetry supports both HTTP and gRPC protocols for OTLP (OpenTelemetry Protocol). While HTTP works with all tunneling tools, **gRPC requires TCP tunneling support**, which is only available with ngrok. For gRPC tunneling, use just the base endpoint without path suffixes:
 
 #### Setting Up gRPC Tunneling with ngrok
 
@@ -227,7 +227,7 @@ traceExporter: new OTLPTraceExporterGrpc({
 | **Firewall/Proxy**   | Better compatibility                       | May have issues                     |
 | **Use Cases**        | Most development scenarios                 | High-performance requirements       |
 
-## Important Considerations
+## Best Practices
 
 ### Security
 

@@ -30,15 +30,15 @@ const undiciInstrumentationConfig = {
 } satisfies UndiciInstrumentationConfig;
 
 /**
- * Get the instrumentations for a given preset.
+ * Gets the instrumentations for a given preset.
  *
  * @param preset - The preset to get the instrumentations for. *
  * @returns The instrumentations for the given preset:
  * - `full`: All the Node.js [auto-instrumentations](https://www.npmjs.com/package/@opentelemetry/auto-instrumentations-node)
  * - `simple`: Instrumentations for:
- *   [Http](https://www.npmjs.com/package/@opentelemetry/instrumentation-http),
- *   [GraphQL](https://www.npmjs.com/package/@opentelemetry/instrumentation-graphql), and
- *   [Undici](https://www.npmjs.com/package/@opentelemetry/instrumentation-undici)
+ *     - [Http](https://www.npmjs.com/package/@opentelemetry/instrumentation-http),
+ *     - [GraphQL](https://www.npmjs.com/package/@opentelemetry/instrumentation-graphql)
+ *     - [Undici](https://www.npmjs.com/package/@opentelemetry/instrumentation-undici)
  *
  * @throws {Error} If the preset is unknown.
  *

@@ -13,7 +13,7 @@
 import type { EntrypointInstrumentationConfig } from "~/types";
 
 /**
- * Helper to define the telemetry config for an entrypoint.
+ * Helper to define the telemetry configuration for an entrypoint.
  * @param init - The function to initialize the telemetry.
  *
  * @since 0.1.0

@@ -63,7 +63,8 @@ function __getLoggerInternal(
 }
 
 /**
- * Get a logger instance.
+ * Gets a logger instance that can export OpenTelemetry logs.
+ *
  * @param name - The name of the logger
  * @param config - The configuration for the logger
  *

@@ -23,7 +23,7 @@ import type { AnyFunction } from "~/core/instrumentation";
 import type { getLogger } from "~/core/logging";
 
 /**
- * Available log levels for the OpenTelemetry DiagLogger.
+ * Available log levels for the OpenTelemetry `DiagLogger`.
  * @since 0.1.0
  */
 export type DiagnosticsLogLevel = Lowercase<keyof typeof DiagLogLevel>;
@@ -211,7 +211,7 @@ export interface EntrypointInstrumentationConfig<
 }
 
 /**
- * Defines the global telemetry API. These items should be set once per-application.
+ * Defines the global telemetry API. These items should be set once per application.
  * @since 0.1.0
  */
 export interface TelemetryApi {