OpenTelemetry Exporter classes/method description and internal tagging (Azure#13836)

* Adding documentation description and internal tag

* Lint

* Adding doc for service API version enum

* Lint

* Addressing comments

Author: hectorhdzg

sdk/monitor/monitor-opentelemetry-exporter/review/monitor-opentelemetry-exporter.api.md

@@ -8,26 +8,21 @@ import { ExportResult } from '@opentelemetry/core';
 import { ReadableSpan } from '@opentelemetry/tracing';
 import { SpanExporter } from '@opentelemetry/tracing';
 
-// @public (undocumented)
+// @public
 export interface AzureExporterConfig {
-    // (undocumented)
     apiVersion?: ServiceApiVersion;
-    // (undocumented)
     connectionString?: string;
 }
 
-// @public (undocumented)
+// @public
 export class AzureMonitorTraceExporter implements SpanExporter {
     constructor(options?: AzureExporterConfig);
-    // (undocumented)
     export(spans: ReadableSpan[], resultCallback: (result: ExportResult) => void): Promise<void>;
-    // (undocumented)
     shutdown(): Promise<void>;
 }
 
-// @public (undocumented)
+// @public
 export enum ServiceApiVersion {
-    // (undocumented)
     V2 = "2020-09-15_Preview"
 }
 

sdk/monitor/monitor-opentelemetry-exporter/src/Declarations/Constants.ts

@@ -1,17 +1,51 @@
 // Copyright (c) Microsoft Corporation.
 // Licensed under the MIT license.
 
+/**
+ * Azure service API version.
+ */
 export enum ServiceApiVersion {
+  /**
+   * V2 Version
+   */
   V2 = "2020-09-15_Preview"
 }
 
+/**
+ * Default Breeze endpoint.
+ * @internal
+ */
 export const DEFAULT_BREEZE_ENDPOINT = "https://dc.services.visualstudio.com";
+/**
+ * Default Breeze API version.
+ * @internal
+ */
 export const DEFAULT_BREEZE_API_VERSION = ServiceApiVersion.V2;
+/**
+ * Default Live Metrics endpoint.
+ * @internal
+ */
 export const DEFAULT_LIVEMETRICS_ENDPOINT = "https://rt.services.visualstudio.com";
+/**
+ * Default Live Metrics host.
+ * @internal
+ */
 export const DEFAULT_LIVEMETRICS_HOST = "rt.services.visualstudio.com";
+/**
+ * Connection string environment variable name.
+ * @internal
+ */
 export const ENV_CONNECTION_STRING = "APPLICATIONINSIGHTS_CONNECTION_STRING";
+/**
+ * Instrumentation key environment variable name.
+ * @internal
+ */
 export const ENV_INSTRUMENTATION_KEY = "APPINSIGHTS_INSTRUMENTATIONKEY";
 
+/**
+ * QuickPulse metric counter names.
+ * @internal
+ */
 export enum QuickPulseCounter {
   // Memory
   COMMITTED_BYTES = "\\Memory\\Committed Bytes",
@@ -33,6 +67,10 @@ export enum QuickPulseCounter {
   EXCEPTION_RATE = "\\ApplicationInsights\\Exceptions/Sec"
 }
 
+/**
+ * Performance metric counter names.
+ * @internal
+ */
 export enum PerformanceCounter {
   // Memory
   PRIVATE_BYTES = "\\Process(??APP_WIN32_PROC??)\\Private Bytes",
@@ -49,6 +87,7 @@ export enum PerformanceCounter {
 
 /**
  * Map a PerformanceCounter/QuickPulseCounter to a QuickPulseCounter. If no mapping exists, mapping is *undefined*
+ * @internal
  */
 export const PerformanceToQuickPulseCounter: { [key: string]: QuickPulseCounter } = {
   [PerformanceCounter.PROCESSOR_TIME]: QuickPulseCounter.PROCESSOR_TIME,
@@ -64,8 +103,10 @@ export const PerformanceToQuickPulseCounter: { [key: string]: QuickPulseCounter
   [QuickPulseCounter.EXCEPTION_RATE]: QuickPulseCounter.EXCEPTION_RATE
 };
 
-// Note: Explicitly define these types instead of using enum due to
-// potential 'export enum' issues with typescript < 2.0.
+/**
+ * QuickPulse document types.
+ * @internal
+ */
 export type QuickPulseDocumentType =
   | "Event"
   | "Exception"
@@ -74,6 +115,10 @@ export type QuickPulseDocumentType =
   | "Request"
   | "RemoteDependency"
   | "Availability";
+/**
+ * QuickPulse telemetry types.
+ * @internal
+ */
 export type QuickPulseType =
   | "EventTelemetryDocument"
   | "ExceptionTelemetryDocument"
@@ -83,7 +128,10 @@ export type QuickPulseType =
   | "DependencyTelemetryDocument"
   | "AvailabilityTelemetryDocument";
 
-// OpenTelemetry Span Attributes
+/**
+ * OpenTelemetry Span Attributes.
+ * @internal
+ */
 export const SpanAttribute = {
   // HTTP
   HttpHost: "http.host",
@@ -98,6 +146,10 @@ export const SpanAttribute = {
   GrpcService: "rpc.service" // rpc not grpc
 };
 
+/**
+ * OpenTelemetry dependency type names.
+ * @internal
+ */
 export const DependencyTypeName = {
   Grpc: "GRPC",
   Http: "HTTP",

sdk/monitor/monitor-opentelemetry-exporter/src/Declarations/Contracts/Constants.ts

@@ -3,10 +3,15 @@
 
 /**
  * Subset of Connection String fields which this SDK can parse. Lower-typecased to
- * allow for case-insensitivity across field names
+ * allow for case-insensitivity across field names.
+ * @internal
  */
 export type ConnectionString = { [key in ConnectionStringKey]?: string };
 
+/**
+ * ConnectionString keys.
+ * @internal
+ */
 export type ConnectionStringKey =
   | "authorization"
   | "instrumentationkey"

sdk/monitor/monitor-opentelemetry-exporter/src/config.ts

@@ -10,13 +10,25 @@ import {
 const DEFAULT_BATCH_SEND_RETRY_INTERVAL_MS = 60_000;
 const DEFAULT_MAX_CONSECUTIVE_FAILURES_BEFORE_WARNING = 10;
 
+/**
+ * Provides configuration options for AzureMonitorTraceExporter.
+ */
 export interface AzureExporterConfig {
-  // Setup String
+  /**
+   * Azure Monitor Connection String, if not provided the exporter will try to use environment variable APPLICATIONINSIGHTS_CONNECTION_STRING
+   * Ex: "InstrumentationKey=00000000-0000-0000-0000-000000000000;IngestionEndpoint=https://dc.services.visualstudio.com"
+   */
   connectionString?: string;
-  // Azure service API version
+  /**
+   * Azure service API version.
+   */
   apiVersion?: ServiceApiVersion;
 }
 
+/**
+ * Internal Azure exporter configuration
+ * @internal
+ */
 export interface AzureExporterInternalConfig {
   instrumentationKey: string;
   batchSendRetryIntervalMs: number;
@@ -25,6 +37,10 @@ export interface AzureExporterInternalConfig {
   apiVersion: ServiceApiVersion;
 }
 
+/**
+ * Internal default Azure exporter configuration
+ * @internal
+ */
 export const DEFAULT_EXPORTER_CONFIG: AzureExporterInternalConfig = {
   instrumentationKey: "",
   endpointUrl: DEFAULT_BREEZE_ENDPOINT,

sdk/monitor/monitor-opentelemetry-exporter/src/export/trace.ts

@@ -18,6 +18,9 @@ import { ENV_CONNECTION_STRING } from "../Declarations/Constants";
 import { TelemetryItem as Envelope } from "../generated";
 import { readableSpanToEnvelope } from "../utils/spanUtils";
 
+/**
+ * Azure Monitor OpenTelemetry Trace Exporter.
+ */
 export class AzureMonitorTraceExporter implements SpanExporter {
   private readonly _persister: PersistentStorage;
 
@@ -27,6 +30,10 @@ export class AzureMonitorTraceExporter implements SpanExporter {
 
   private readonly _options: AzureExporterInternalConfig;
 
+  /**
+   * Initializes a new instance of the AzureMonitorTraceExporter class.
+   * @param AzureExporterConfig - Exporter configuration.
+   */
   constructor(options: AzureExporterConfig = {}) {
     const connectionString = options.connectionString || process.env[ENV_CONNECTION_STRING];
     this._options = {
@@ -122,6 +129,11 @@ export class AzureMonitorTraceExporter implements SpanExporter {
     }
   }
 
+  /**
+   * Export OpenTelemetry spans.
+   * @param spans - Spans to export.
+   * @param resultCallback - Result callback.
+   */
   async export(
     spans: ReadableSpan[],
     resultCallback: (result: ExportResult) => void
@@ -133,6 +145,9 @@ export class AzureMonitorTraceExporter implements SpanExporter {
     resultCallback(await this.exportEnvelopes(envelopes));
   }
 
+  /**
+   * Shutdown AzureMonitorTraceExporter.
+   */
   async shutdown(): Promise<void> {
     diag.info("Azure Monitor Trace Exporter shutting down");
     return this._sender.shutdown();

sdk/monitor/monitor-opentelemetry-exporter/src/platform/nodejs/constants.ts

@@ -1,6 +1,10 @@
 // Copyright (c) Microsoft Corporation.
 // Licensed under the MIT license.
 
+/**
+ * SDK info
+ * @internal
+ */
 export const SDK_INFO = {
   NAME: "opentelemetry",
   RUNTIME: "node",

sdk/monitor/monitor-opentelemetry-exporter/src/platform/nodejs/context/context.ts

@@ -14,6 +14,10 @@ type PackageJson = { version: string };
 
 let instance: Context | null = null;
 
+/**
+ * Azure Telemetry context.
+ * @internal
+ */
 export class Context {
   public tags: Tags;
 
@@ -145,6 +149,10 @@ export class Context {
   }
 }
 
+/**
+ * Singleton Context instance.
+ * @internal
+ */
 export function getInstance(exporterPrefix?: string, appPrefix?: string): Context {
   if (!instance) {
     instance = new Context(exporterPrefix, appPrefix);

sdk/monitor/monitor-opentelemetry-exporter/src/platform/nodejs/httpSender.ts

@@ -10,6 +10,10 @@ import {
 } from "../../generated";
 import { AzureExporterInternalConfig } from "../../config";
 
+/**
+ * Exporter HTTP sender class
+ * @internal
+ */
 export class HttpSender implements Sender {
   private readonly _appInsightsClient: ApplicationInsightsClient;
   private _appInsightsClientOptions: ApplicationInsightsClientOptionalParams;
@@ -25,6 +29,10 @@ export class HttpSender implements Sender {
     });
   }
 
+  /**
+   * Send Azure envelopes
+   * @internal
+   */
   async send(envelopes: Envelope[]): Promise<SenderResult> {
     try {
       const { _response: res } = await this._appInsightsClient.track(envelopes);
@@ -34,6 +42,10 @@ export class HttpSender implements Sender {
     }
   }
 
+  /**
+   * Shutdown sender
+   * @internal
+   */
   async shutdown(): Promise<void> {
     diag.info("HttpSender shutting down");
   }

sdk/monitor/monitor-opentelemetry-exporter/src/platform/nodejs/persist/fileSystemHelpers.ts

@@ -12,6 +12,7 @@ const mkdirAsync = promisify(fs.mkdir);
 
 /**
  * Computes the size (in bytes) of all files in a directory at the root level. Asynchronously.
+ * @internal
  */
 export const getShallowDirectorySize = async (directory: string): Promise<number> => {
   // Get the directory listing
@@ -30,6 +31,10 @@ export const getShallowDirectorySize = async (directory: string): Promise<number
   return totalSize;
 };
 
+/**
+ * Validate directory exists.
+ * @internal
+ */
 export const confirmDirExists = async (directory: string): Promise<void> => {
   try {
     const stats = await lstatAsync(directory);

sdk/monitor/monitor-opentelemetry-exporter/src/platform/nodejs/persist/fileSystemPersist.ts

@@ -16,6 +16,10 @@ const readFileAsync = promisify(fs.readFile);
 const unlinkAsync = promisify(fs.unlink);
 const writeFileAsync = promisify(fs.writeFile);
 
+/**
+ * File system persist class.
+ * @internal
+ */
 export class FileSystemPersist implements PersistentStorage {
   static TEMPDIR_PREFIX = "ot-azure-exporter-";