@azure/monitor-opentelemetry 1.8.1 → 1.9.0

package/README.md

@@ -27,8 +27,8 @@ See our [support policy](https://github.com/Azure/azure-sdk-for-js/blob/main/SUP
 
 > _Important:_ `useAzureMonitor` must be called _before_ you import anything else. There may be resulting telemetry loss if other libraries are imported first.
 
-```typescript
-import { useAzureMonitor, AzureMonitorOpenTelemetryOptions } from "@azure/monitor-opentelemetry";
+```ts snippet:ReadmeSampleUseAzureMonitor
+import { AzureMonitorOpenTelemetryOptions, useAzureMonitor } from "@azure/monitor-opentelemetry";
 
 const options: AzureMonitorOpenTelemetryOptions = {
   azureMonitorExporterOptions: {
@@ -43,9 +43,9 @@ useAzureMonitor(options);
 
 ## Configuration
 
-```typescript
-import { AzureMonitorOpenTelemetryOptions, useAzureMonitor } from "@azure/monitor-opentelemetry";
+```ts snippet:ReadmeSampleConfiguration
 import { Resource } from "@opentelemetry/resources";
+import { AzureMonitorOpenTelemetryOptions, useAzureMonitor } from "@azure/monitor-opentelemetry";
 
 const resource = new Resource({ testAttribute: "testValue" });
 const options: AzureMonitorOpenTelemetryOptions = {
@@ -82,23 +82,88 @@ const options: AzureMonitorOpenTelemetryOptions = {
   logRecordProcessors: [],
   spanProcessors: [],
 };
-
 useAzureMonitor(options);
 ```
 
-|Property|Description|Default|
-| ------------------------------- |------------------------------------------------------------------------------------------------------------|-------|
-| azureMonitorExporterOptions     | Azure Monitor OpenTelemetry Exporter Configuration. [More info here](https://github.com/Azure/azure-sdk-for-js/tree/main/sdk/monitor/monitor-opentelemetry-exporter) | | | |
-| samplingRatio              | Sampling ratio must take a value in the range [0,1], 1 meaning all data will sampled and 0 all Tracing data will be sampled out. | 1|
-| instrumentationOptions| Allow configuration of OpenTelemetry Instrumentations. |  {"http": { enabled: true },"azureSdk": { enabled: false },"mongoDb": { enabled: false },"mySql": { enabled: false },"postgreSql": { enabled: false },"redis": { enabled: false },"bunyan": { enabled: false }, "winston": { enabled: false } }|
-| browserSdkLoaderOptions| Allow configuration of Web Instrumentations. | { enabled: false, connectionString: "" } |
-| resource       | Opentelemetry Resource. [More info here](https://github.com/open-telemetry/opentelemetry-js/tree/main/packages/opentelemetry-resources) ||
-| samplingRatio              | Sampling ratio must take a value in the range [0,1], 1 meaning all data will sampled and 0 all Tracing data will be sampled out. |1|
-| enableLiveMetrics          | Enable/Disable Live Metrics. |true|
-| enableStandardMetrics      | Enable/Disable Standard Metrics. |true|
-| logRecordProcessors        | Array of log record processors to register to the global logger provider. ||
-| spanProcessors             | Array of span processors to register to the global tracer provider. ||
-| enableTraceBasedSamplingForLogs  | Enable log sampling based on trace. |false|                                                                                                                                                                                                                                      |
+<table>
+  <tr>
+    <th>Option</th>
+    <th>Description</th>
+    <th>Default</th>
+  </tr>
+  <tr>
+    <td><code>azureMonitorExporterOptions</code></td>
+    <td>Azure Monitor OpenTelemetry Exporter Configuration. <a href="https://github.com/Azure/azure-sdk-for-js/tree/main/sdk/monitor/monitor-opentelemetry-exporter">More info here</a></td>
+    <td></td>
+  </tr>
+  <tr>
+    <td><code>samplingRatio</code></td>
+    <td>Sampling ratio must take a value in the range [0,1], 1 meaning all data will sampled and 0 all Tracing data will be sampled out.</td>
+    <td><code>1</code></td>
+  </tr>
+  <tr>
+    <td><code>instrumentationOptions</code></td>
+    <td>Instrumentation libraries configuration. <a href="#instrumentation-libraries">More info here</a></td>
+    <td>
+      <pre><code class="language-javascript">
+{
+  http: { enabled: true },
+  azureSdk: { enabled: false },
+  mongoDb: { enabled: false },
+  mySql: { enabled: false },
+  postgreSql: { enabled: false },
+  redis: { enabled: false },
+  bunyan: { enabled: false }, 
+  winston: { enabled: false } 
+}
+      </code></pre>
+    </td>
+  </tr>
+  <tr>
+    <td><code>browserSdkLoaderOptions</code></td>
+    <td>Allow configuration of Web Instrumentations.</td>
+    <td>
+      <pre>
+        <code class="language-javascript">
+{ 
+  enabled: false, 
+  connectionString: "" 
+}
+        </code>
+      </pre>
+    </td>
+  </tr>
+  <tr>
+    <td><code>resource</code></td>
+    <td>Opentelemetry Resource. <a href="https://github.com/open-telemetry/opentelemetry-js/tree/main/packages/opentelemetry-resources">More info here</a></td>
+    <td></td>
+  </tr>
+  <tr>
+    <td><code>enableLiveMetrics</code></td>
+    <td>Enable/Disable Live Metrics.</td>
+    <td><code>true</code></td>
+  </tr>
+  <tr>
+    <td><code>enableStandardMetrics</code></td>
+    <td>Enable/Disable Standard Metrics. </td>
+    <td><code>true</code></td>
+  </tr>
+  <tr>
+    <td><code>logRecordProcessors</code></td>
+    <td>Array of log record processors to register to the global logger provider. </td>
+    <td></td>
+  </tr>
+  <tr>
+    <td><code>spanProcessors</code></td>
+    <td>Array of span processors to register to the global tracer provider. </td>
+    <td></td>
+  </tr>
+  <tr>
+    <td><code>enableTraceBasedSamplingForLogs</code></td>
+    <td>Enable log sampling based on trace.</td>
+    <td><code>false</code></td>
+  </tr>
+</table>
 
 Options could be set using configuration file `applicationinsights.json` located under root folder of @azure/monitor-opentelemetry package installation folder, Ex: `node_modules/@azure/monitor-opentelemetry`. These configuration values will be applied to all AzureMonitorOpenTelemetryClient instances.
 
@@ -118,11 +183,8 @@ Options could be set using configuration file `applicationinsights.json` located
 
 Custom JSON file could be provided using `APPLICATIONINSIGHTS_CONFIGURATION_FILE` environment variable.
 
-```javascript
-process.env.APPLICATIONINSIGHTS_CONFIGURATION_FILE =
-  "C:/applicationinsights/config/customConfig.json";
-
-// Application Insights SDK setup....
+```ts snippet:ReadmeSampleCustomConfig
+process.env["APPLICATIONINSIGHTS_CONFIGURATION_FILE"] = "path/to/customConfig.json";
 ```
 
 ## Instrumentation libraries
@@ -153,18 +215,17 @@ The following OpenTelemetry Instrumentation libraries are included as part of Az
 
 Other OpenTelemetry Instrumentations are available [here](https://github.com/open-telemetry/opentelemetry-js-contrib/tree/main/plugins/node) and could be added using TracerProvider in AzureMonitorOpenTelemetryClient.
 
-```typescript
+```ts snippet:ReadmeSampleCustomInstrumentation
 import { useAzureMonitor } from "@azure/monitor-opentelemetry";
-import { metrics, trace } from "@opentelemetry/api";
 import { registerInstrumentations } from "@opentelemetry/instrumentation";
+import { trace, metrics } from "@opentelemetry/api";
 import { ExpressInstrumentation } from "@opentelemetry/instrumentation-express";
 
 useAzureMonitor();
-const instrumentations = [new ExpressInstrumentation()];
 registerInstrumentations({
   tracerProvider: trace.getTracerProvider(),
   meterProvider: metrics.getMeterProvider(),
-  instrumentations: instrumentations,
+  instrumentations: [new ExpressInstrumentation()],
 });
 ```
 
@@ -184,18 +245,22 @@ Further information on usage of the browser SDK loader can be found [here](https
 
 You might set the Cloud Role Name and the Cloud Role Instance via [OpenTelemetry Resource](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/resource/sdk.md#resource-sdk) attributes.
 
-```typescript
-import { useAzureMonitor, AzureMonitorOpenTelemetryOptions } from "@azure/monitor-opentelemetry";
+```ts snippet:ReadmeSampleSetRoleNameAndInstance
 import { Resource } from "@opentelemetry/resources";
-import { SemanticResourceAttributes } from "@opentelemetry/semantic-conventions";
+import {
+  ATTR_SERVICE_NAME,
+  SEMRESATTRS_SERVICE_NAMESPACE,
+  SEMRESATTRS_SERVICE_INSTANCE_ID,
+} from "@opentelemetry/semantic-conventions";
+import { AzureMonitorOpenTelemetryOptions, useAzureMonitor } from "@azure/monitor-opentelemetry";
 
 // ----------------------------------------
 // Setting role name and role instance
 // ----------------------------------------
 const customResource = Resource.EMPTY;
-customResource.attributes[SemanticResourceAttributes.SERVICE_NAME] = "my-helloworld-service";
-customResource.attributes[SemanticResourceAttributes.SERVICE_NAMESPACE] = "my-namespace";
-customResource.attributes[SemanticResourceAttributes.SERVICE_INSTANCE_ID] = "my-instance";
+customResource.attributes[ATTR_SERVICE_NAME] = "my-helloworld-service";
+customResource.attributes[SEMRESATTRS_SERVICE_NAMESPACE] = "my-namespace";
+customResource.attributes[SEMRESATTRS_SERVICE_INSTANCE_ID] = "my-instance";
 
 const options: AzureMonitorOpenTelemetryOptions = { resource: customResource };
 useAzureMonitor(options);
@@ -224,23 +289,24 @@ Any [attributes](#add-span-attributes) you add to spans are exported as custom p
 
 Use a custom processor:
 
-```typescript
-import { useAzureMonitor, AzureMonitorOpenTelemetryOptions } from "@azure/monitor-opentelemetry";
-import { ReadableSpan, Span, SpanProcessor } from "@opentelemetry/sdk-trace-base";
-import { SemanticAttributes } from "@opentelemetry/semantic-conventions";
+```ts snippet:ReadmeSampleAddCustomProperty
+import { SpanProcessor, ReadableSpan } from "@opentelemetry/sdk-trace-base";
+import { Span } from "@opentelemetry/api";
+import { SEMATTRS_HTTP_CLIENT_IP } from "@opentelemetry/semantic-conventions";
+import { AzureMonitorOpenTelemetryOptions, useAzureMonitor } from "@azure/monitor-opentelemetry";
 
 class SpanEnrichingProcessor implements SpanProcessor {
-  forceFlush(): Promise<void> {
-    return Promise.resolve();
+  async forceFlush(): Promise<void> {
+    // Flush code here
   }
-  shutdown(): Promise<void> {
-    return Promise.resolve();
+  async shutdown(): Promise<void> {
+    // shutdown code here
   }
   onStart(_span: Span): void {}
-  onEnd(span: ReadableSpan) {
+  onEnd(span: ReadableSpan): void {
     span.attributes["CustomDimension1"] = "value1";
     span.attributes["CustomDimension2"] = "value2";
-    span.attributes[SemanticAttributes.HTTP_CLIENT_IP] = "<IP Address>";
+    span.attributes[SEMATTRS_HTTP_CLIENT_IP] = "<IP Address>";
   }
 }
 
@@ -249,6 +315,7 @@ const options: AzureMonitorOpenTelemetryOptions = {
   // Add the SpanEnrichingProcessor
   spanProcessors: [new SpanEnrichingProcessor()],
 };
+
 useAzureMonitor(options);
 ```
 
@@ -256,43 +323,42 @@ useAzureMonitor(options);
 
 Use a custom span processor and log record processor in order to attach and correlate operation name from requests to dependencies and logs.
 
-```typescript
-import { useAzureMonitor, AzureMonitorOpenTelemetryOptions } from "@azure/monitor-opentelemetry";
-import { ReadableSpan, Span, SpanProcessor } from "@opentelemetry/sdk-trace-base";
-import { LogRecordProcessor } from "@opentelemetry/sdk-logs";
-import { SemanticAttributes } from "@opentelemetry/semantic-conventions";
+```ts snippet:ReadmeSampleAddOperationName
+import { SpanProcessor, ReadableSpan } from "@opentelemetry/sdk-trace-base";
+import { Span, Context, trace } from "@opentelemetry/api";
 import { AI_OPERATION_NAME } from "@azure/monitor-opentelemetry-exporter";
-import { Context, trace } from "@opentelemetry/api";
+import { LogRecordProcessor, LogRecord } from "@opentelemetry/sdk-logs";
+import { AzureMonitorOpenTelemetryOptions, useAzureMonitor } from "@azure/monitor-opentelemetry";
 
 class SpanEnrichingProcessor implements SpanProcessor {
-  forceFlush(): Promise<void> {
-    return Promise.resolve();
+  async forceFlush(): Promise<void> {
+    // Flush code here
   }
-  shutdown(): Promise<void> {
-    return Promise.resolve();
+  async shutdown(): Promise<void> {
+    // shutdown code here
   }
   onStart(_span: Span, _context: Context): void {
     const parentSpan = trace.getSpan(_context);
     if (parentSpan && "name" in parentSpan) {
       // If the parent span has a name we can assume it is a ReadableSpan and cast it.
-      _span.attributes[AI_OPERATION_NAME] = (parentSpan as unknown as ReadableSpan).name;
+      _span.setAttribute(AI_OPERATION_NAME, (parentSpan as unknown as ReadableSpan).name);
     }
   }
-  onEnd(span: ReadableSpan) {}
+  onEnd(_span: ReadableSpan): void {}
 }
 
 class LogRecordEnrichingProcessor implements LogRecordProcessor {
-  forceFlush(): Promise<void> {
-    return Promise.resolve();
+  async forceFlush(): Promise<void> {
+    // Flush code here
   }
-  shutdown(): Promise<void> {
-    return Promise.resolve();
+  async shutdown(): Promise<void> {
+    // shutdown code here
   }
-  onEmit(_logRecord, _context): void {
+  onEmit(_logRecord: LogRecord, _context: Context): void {
     const parentSpan = trace.getSpan(_context);
     if (parentSpan && "name" in parentSpan) {
       // If the parent span has a name we can assume it is a ReadableSpan and cast it.
-      _logRecord.attributes[AI_OPERATION_NAME] = (parentSpan as unknown as ReadableSpan).name;
+      _logRecord.setAttribute(AI_OPERATION_NAME, (parentSpan as unknown as ReadableSpan).name);
     }
   }
 }
@@ -303,6 +369,7 @@ const options: AzureMonitorOpenTelemetryOptions = {
   spanProcessors: [new SpanEnrichingProcessor()],
   logRecordProcessors: [new LogRecordEnrichingProcessor()],
 };
+
 useAzureMonitor(options);
 ```
 
@@ -314,14 +381,13 @@ You might use the following ways to filter out telemetry before it leaves your a
 
     The following example shows how to exclude a certain URL from being tracked by using the [HTTP/HTTPS instrumentation library](https://github.com/open-telemetry/opentelemetry-js/tree/main/experimental/packages/opentelemetry-instrumentation-http):
 
-    ```typescript
+    ```ts snippet:ReadmeSampleExcludeUrl
+    import { HttpInstrumentationConfig } from "@opentelemetry/instrumentation-http";
+    import { IncomingMessage, RequestOptions } from "node:http";
     import {
-      useAzureMonitor,
       AzureMonitorOpenTelemetryOptions,
+      useAzureMonitor,
     } from "@azure/monitor-opentelemetry";
-    import { IncomingMessage } from "http";
-    import { RequestOptions } from "https";
-    import { HttpInstrumentationConfig } from "@opentelemetry/instrumentation-http";
 
     const httpInstrumentationConfig: HttpInstrumentationConfig = {
       enabled: true,
@@ -340,30 +406,38 @@ You might use the following ways to filter out telemetry before it leaves your a
         return false;
       },
     };
+
     const options: AzureMonitorOpenTelemetryOptions = {
       instrumentationOptions: {
         http: httpInstrumentationConfig,
       },
     };
+
     useAzureMonitor(options);
     ```
 
 1.  Use a custom processor. You can use a custom span processor to exclude certain spans from being exported. To mark spans to not be exported, set `TraceFlag` to `DEFAULT`.
     Use the add [custom property example](#add-a-custom-property-to-a-trace), but replace the following lines of code:
 
-        ```typescript
-        ...
-        import { SpanKind, TraceFlags } from "@opentelemetry/api";
-        import { ReadableSpan, SpanProcessor } from "@opentelemetry/sdk-trace-base";
+        ```ts snippet:ReadmeSampleCustomProcessor
+        import { SpanProcessor, ReadableSpan } from "@opentelemetry/sdk-trace-base";
+        import { Span, Context, SpanKind, TraceFlags } from "@opentelemetry/api";
 
         class SpanEnrichingProcessor implements SpanProcessor {
-            ...
-
-            onEnd(span: ReadableSpan) {
-                if(span.kind == SpanKind.INTERNAL){
-                    span.spanContext().traceFlags = TraceFlags.NONE;
-                }
+          async forceFlush(): Promise<void> {
+            // Force flush code here
+          }
+          onStart(_span: Span, _parentContext: Context): void {
+            // Normal code here
+          }
+          async shutdown(): Promise<void> {
+            // Shutdown code here
+          }
+          onEnd(span: ReadableSpan): void {
+            if (span.kind === SpanKind.INTERNAL) {
+              span.spanContext().traceFlags = TraceFlags.NONE;
             }
+          }
         }
         ```
 
@@ -393,18 +467,18 @@ The following table shows the recommended aggregation types] for each of the Ope
 The [OpenTelemetry Specification](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/metrics/api.md#instrument)
 describes the instruments and provides examples of when you might use each one.
 
-```typescript
+```ts snippet:ReadmeSampleCustomMetrics
 import { useAzureMonitor } from "@azure/monitor-opentelemetry";
-import { ObservableResult, metrics } from "@opentelemetry/api";
+import { metrics, ObservableResult } from "@opentelemetry/api";
 
 useAzureMonitor();
 const meter = metrics.getMeter("testMeter");
 
-let histogram = meter.createHistogram("histogram");
-let counter = meter.createCounter("counter");
-let gauge = meter.createObservableGauge("gauge");
+const histogram = meter.createHistogram("histogram");
+const counter = meter.createCounter("counter");
+const gauge = meter.createObservableGauge("gauge");
 gauge.addCallback((observableResult: ObservableResult) => {
-  let randomNumber = Math.floor(Math.random() * 100);
+  const randomNumber = Math.floor(Math.random() * 100);
   observableResult.observe(randomNumber, { testKey: "testValue" });
 });
 
@@ -424,14 +498,14 @@ However, you may want to manually report exceptions beyond what instrumention li
 For instance, exceptions caught by your code are _not_ ordinarily not reported, and you may wish to report them
 and thus draw attention to them in relevant experiences including the failures blade and end-to-end transaction view.
 
-```typescript
+```ts snippet:ReadmeSampleCustomExceptions
 import { useAzureMonitor } from "@azure/monitor-opentelemetry";
 import { trace, Exception } from "@opentelemetry/api";
 
 useAzureMonitor();
 const tracer = trace.getTracer("testMeter");
 
-let span = tracer.startSpan("hello");
+const span = tracer.startSpan("hello");
 try {
   throw new Error("Test Error");
 } catch (error) {
@@ -445,13 +519,12 @@ try {
 
 Azure Monitor OpenTelemetry uses the OpenTelemetry API Logger for internal logs. To enable it, use the following code:
 
-```typescript
+```ts snippet:ReadmeSampleSelfDiagnostics
 import { useAzureMonitor } from "@azure/monitor-opentelemetry";
-import { DiagLogLevel } from "@opentelemetry/api";
 
-process.env.APPLICATIONINSIGHTS_INSTRUMENTATION_LOGGING_LEVEL = "VERBOSE";
-process.env.APPLICATIONINSIGHTS_LOG_DESTINATION = "file";
-process.env.APPLICATIONINSIGHTS_LOGDIR = "C:/applicationinsights/logs";
+process.env["APPLICATIONINSIGHTS_INSTRUMENTATION_LOGGING_LEVEL"] = "VERBOSE";
+process.env["APPLICATIONINSIGHTS_LOG_DESTINATION"] = "file";
+process.env["APPLICATIONINSIGHTS_LOGDIR"] = "path/to/logs";
 
 useAzureMonitor();
 ```
@@ -477,5 +550,3 @@ If you cannot your library in the registry, feel free to suggest a new plugin re
 ## Contributing
 
 If you'd like to contribute to this library, please read the [contributing guide](https://github.com/Azure/azure-sdk-for-js/blob/main/CONTRIBUTING.md) to learn more about how to build and test the code.
-
-![Impressions](https://azure-sdk-impressions.azurewebsites.net/api/impressions/azure-sdk-for-js/sdk/monitor/monitor-opentelemetry/README.png)