@herrromich/az-functions 1.0.0

package/src/logger/bindings.ts

@@ -0,0 +1,56 @@
+import { AzureMonitorLogExporter } from '@azure/monitor-opentelemetry-exporter';
+import { resourceFromAttributes } from '@opentelemetry/resources';
+import { BatchLogRecordProcessor, LoggerProvider } from '@opentelemetry/sdk-logs';
+import { ATTR_SERVICE_INSTANCE_ID, ATTR_SERVICE_NAME, ATTR_SERVICE_VERSION } from '@opentelemetry/semantic-conventions';
+import { ResolutionContext } from 'inversify';
+import * as winston from 'winston';
+import { AzFunctionsTransport } from './log-transport.service';
+import {
+  LOG_LEVELS,
+  Logger,
+  LOGGER_NAME_META_KEY,
+  LOGGER_NAME_PROVIDER,
+  LoggerFactory,
+  OtelConfiguration,
+} from './logger.model';
+
+export function bindWinstonLogger(context: ResolutionContext): winston.Logger {
+  const transport = context.get(AzFunctionsTransport);
+  return winston.createLogger({
+    level: 'silly',
+    levels: LOG_LEVELS,
+    format: winston.format.combine(winston.format.timestamp(), winston.format.splat(), winston.format.metadata()),
+    transports: [transport],
+  });
+}
+
+export function bindLoggerFactory(context: ResolutionContext): LoggerFactory {
+  const logger = context.get(winston.Logger);
+  const loggerNameProvider = context.get(LOGGER_NAME_PROVIDER, { optional: true });
+  return (loggerName?: string): Logger => {
+    let derivedLoggerName = loggerName;
+    if (loggerName !== undefined) {
+      return logger.child({ loggerName });
+    }
+    if (loggerNameProvider !== undefined) {
+      const obj = {};
+      Error.captureStackTrace(obj);
+      const stack = (obj as { stack?: string }).stack;
+      const stackEntry = stack?.split('\n')[2];
+      derivedLoggerName = loggerNameProvider(stackEntry);
+    }
+    return logger.child({ [LOGGER_NAME_META_KEY]: derivedLoggerName ?? '' });
+  };
+}
+
+export function bindOtelLoggerProvider(otelConfiguration: OtelConfiguration): LoggerProvider {
+  const connectionString = otelConfiguration?.applicationInsightsConnectionString;
+  return new LoggerProvider({
+    resource: resourceFromAttributes({
+      [ATTR_SERVICE_NAME]: otelConfiguration?.serviceName,
+      [ATTR_SERVICE_INSTANCE_ID]: otelConfiguration?.serviceInstanceId,
+      [ATTR_SERVICE_VERSION]: otelConfiguration?.serviceVersion,
+    }),
+    processors: [new BatchLogRecordProcessor(new AzureMonitorLogExporter({ connectionString }))],
+  });
+}

package/src/logger/index.ts

@@ -0,0 +1,26 @@
+import { ContainerModule } from 'inversify';
+import * as winston from 'winston';
+import { bindLoggerFactory, bindOtelLoggerProvider, bindWinstonLogger } from './bindings';
+import { LogLevelService } from './log-level.service';
+import { AzFunctionsTransport } from './log-transport.service';
+import { DEFAULT_LOG_LEVEL, LOGGER_FACTORY, LOGGER_PROVIDER, LoggerConfiguration } from './logger.model';
+import { OtelLogger } from './otel.logger';
+
+export * from './logger.model';
+export * from './logger.utils';
+export * from './trie-search.service';
+
+export function provideLoggerModule(loggerConfiguration?: LoggerConfiguration): ContainerModule {
+  return new ContainerModule(options => {
+    options.bind(LogLevelService).toSelf();
+    options.bind(AzFunctionsTransport).toSelf();
+    options.bind(winston.Logger).toDynamicValue(context => bindWinstonLogger(context));
+    options.bind(LOGGER_FACTORY).toFactory(context => bindLoggerFactory(context));
+    options.bind(DEFAULT_LOG_LEVEL).toConstantValue(loggerConfiguration?.defaultLogLevel ?? 'info');
+    if (loggerConfiguration?.otelConfiguration !== undefined) {
+      const otelConfiguration = loggerConfiguration.otelConfiguration;
+      options.bind(OtelLogger).toSelf();
+      options.bind(LOGGER_PROVIDER).toDynamicValue(() => bindOtelLoggerProvider(otelConfiguration));
+    }
+  });
+}

package/src/logger/log-level.service.ts

@@ -0,0 +1,14 @@
+import { inject, injectable, optional } from 'inversify';
+import { DEFAULT_LOG_LEVEL, LOG_LEVEL_PROVIDER, LogLevel, LogLevelProvider } from './logger.model';
+
+@injectable()
+export class LogLevelService {
+  constructor(
+    @inject(LOG_LEVEL_PROVIDER) @optional() private readonly logLevelsProvider: LogLevelProvider | undefined,
+    @inject(DEFAULT_LOG_LEVEL) private readonly defaultLogLevel: LogLevel,
+  ) {}
+
+  getLogLevel(loggerName: string | undefined): LogLevel {
+    return this.logLevelsProvider?.getLogLevel(loggerName) ?? this.defaultLogLevel;
+  }
+}

package/src/logger/log-transport.service.ts

@@ -0,0 +1,162 @@
+import { InvocationContext } from '@azure/functions';
+import { ORIGINAL_INVOCATION_CONTEXT_VALUE_KEY, PLATFORM_CONTEXT_MANAGER, PlatformContextManager } from 'context';
+import { inject, injectable, optional } from 'inversify';
+import * as Transport from 'winston-transport';
+import { LogLevelService } from './log-level.service';
+import {
+  CONTEXT_LOGGER_METADATA,
+  DEFAULT_LOG_LEVEL,
+  LOG_LEVELS,
+  LOGGER_NAME_META_KEY,
+  LogLevel,
+  PlatformLogInfo,
+} from './logger.model';
+import { sanitizeMetadata, SanitizerOptions } from './logger.utils';
+import { OtelLogger } from './otel.logger';
+
+function isLogLevel(level: string): level is LogLevel {
+  return level in LOG_LEVELS;
+}
+export type InvocationContextLogger = Pick<InvocationContext, 'log' | 'trace' | 'debug' | 'info' | 'warn' | 'error'>;
+
+export const LOG_METHOD_MAP: Record<LogLevel, keyof InvocationContextLogger> = {
+  error: 'error',
+  warn: 'warn',
+  info: 'info',
+  http: 'info',
+  verbose: 'info',
+  debug: 'debug',
+  silly: 'trace',
+};
+
+const SANITIZER_OPTIONS: Partial<Record<LogLevel, SanitizerOptions>> = {
+  error: {
+    maxDepth: Number.MAX_VALUE,
+    maxArrayLength: Number.MAX_VALUE,
+    maxKeysCount: Number.MAX_VALUE,
+    maxStringLength: Number.MAX_VALUE,
+  },
+  warn: { maxDepth: 10 },
+  http: { maxDepth: 5, maxArrayLength: 10 },
+  verbose: { maxDepth: 10 },
+  debug: { maxDepth: 20, maxArrayLength: 25, maxKeysCount: 25, maxStringLength: 1000 },
+  silly: {
+    maxDepth: Number.MAX_VALUE,
+    maxArrayLength: Number.MAX_VALUE,
+    maxKeysCount: Number.MAX_VALUE,
+    maxStringLength: Number.MAX_VALUE,
+  },
+};
+
+interface LogMetadata {
+  timestamp: string;
+  [LOGGER_NAME_META_KEY]?: string;
+  message?: string;
+  stack?: string;
+  cause?: unknown;
+  details?: unknown;
+  name?: string;
+}
+
+interface LogInfo {
+  level: LogLevel;
+  message: string;
+  metadata: LogMetadata;
+}
+
+@injectable()
+export class AzFunctionsTransport extends Transport {
+  constructor(
+    @inject(PLATFORM_CONTEXT_MANAGER)
+    private readonly platformContextManager: PlatformContextManager,
+    @inject(DEFAULT_LOG_LEVEL)
+    private readonly defaultLogLevel: LogLevel,
+    @inject(OtelLogger)
+    @optional()
+    private readonly logger: OtelLogger | undefined,
+    private readonly logLevelsService: LogLevelService,
+  ) {
+    super();
+  }
+
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  log(info: any, next: () => void): any {
+    setImmediate(() => {
+      this.emit('logged', info);
+    });
+    const {
+      level,
+      metadata: { loggerName },
+    } = info;
+    const currentLogLevel = isLogLevel(level) ? level : this.defaultLogLevel;
+    const availableLogLevel = this.logLevelsService.getLogLevel(loggerName);
+
+    if (LOG_LEVELS[currentLogLevel] <= LOG_LEVELS[availableLogLevel]) {
+      this.logInternal({
+        level: currentLogLevel,
+        message: info.message,
+        metadata: info.metadata,
+      });
+    }
+    next();
+  }
+
+  private logInternal<T extends LogInfo>(info: T): void {
+    const platformContext = this.platformContextManager.active();
+    const invocationContext = platformContext?.invocationContext;
+    const platformLogInfo = this.getPlatformLogInfo(info, invocationContext);
+    if (this.logger !== undefined) {
+      this.logger.log(platformLogInfo);
+    } else {
+      const fallbackLogger: InvocationContextLogger =
+        platformContext?.getValue<InvocationContext>(ORIGINAL_INVOCATION_CONTEXT_VALUE_KEY) ?? console;
+      const logMethod = LOG_METHOD_MAP[info.level];
+      if (platformLogInfo.metadata !== undefined) {
+        fallbackLogger[logMethod](platformLogInfo.message, platformLogInfo.metadata);
+      } else {
+        fallbackLogger[logMethod](platformLogInfo.message);
+      }
+    }
+  }
+
+  private getPlatformLogInfo<T extends LogInfo>(logInfo: T, invocationContext?: InvocationContext): PlatformLogInfo {
+    const {
+      level,
+      message,
+      metadata: { timestamp, loggerName, ...rest },
+    } = logInfo;
+    const metadata = this.getContextMetadata(level);
+    Object.assign(metadata, rest);
+    const extension =
+      Object.keys(metadata).length > 0
+        ? { metadata: sanitizeMetadata(metadata, SANITIZER_OPTIONS[logInfo.level]) }
+        : {};
+    return {
+      level,
+      timestamp: new Date(timestamp),
+      message,
+      loggerName: loggerName ?? 'unknown',
+      invocationId: invocationContext?.invocationId,
+      traceContext: invocationContext?.traceContext,
+      operationName: invocationContext?.functionName,
+      ...extension,
+    };
+  }
+
+  private getContextMetadata(level: LogLevel): object {
+    const contextLoggerMetadata = this.platformContextManager.active()?.getValue(CONTEXT_LOGGER_METADATA);
+    let metadata: object = {};
+    if (contextLoggerMetadata !== undefined) {
+      let distance = Number.MAX_VALUE;
+      for (const metaLevel of Object.keys(contextLoggerMetadata)) {
+        const typedMetaLevel = metaLevel as LogLevel;
+        const newDistance = LOG_LEVELS[level] - LOG_LEVELS[typedMetaLevel];
+        if (newDistance >= 0 && newDistance < distance) {
+          distance = newDistance;
+          metadata = contextLoggerMetadata[typedMetaLevel]!;
+        }
+      }
+    }
+    return metadata;
+  }
+}

package/src/logger/logger.model.ts

@@ -0,0 +1,261 @@
+import { TraceContext } from '@azure/functions';
+import { AnyValueMap } from '@opentelemetry/api-logs';
+import { LoggerProvider } from '@opentelemetry/sdk-logs';
+import { createPlatformContextValueKey } from 'context';
+import { serviceIdentifier } from 'shared';
+import * as winston from 'winston';
+
+/**
+ * Log levels for the logger.
+ */
+export const LOG_LEVELS = {
+  error: 0,
+  warn: 1,
+  info: 2,
+  http: 3,
+  verbose: 4,
+  debug: 5,
+  silly: 6,
+} as const;
+
+export const LOGGER_NAME_META_KEY = 'loggerName';
+
+export type ContextLoggerMetadata = Partial<Record<LogLevel, object>>;
+export const CONTEXT_LOGGER_METADATA = createPlatformContextValueKey<ContextLoggerMetadata>(
+  'AzFunctionsContext.Logger.Metadata',
+);
+
+/**
+ * Log levels for the logger.
+ *
+ * @see LOG_LEVELS
+ */
+export type LogLevel = keyof typeof LOG_LEVELS;
+
+/**
+ * IoC container identifier for the default log level used by the logger.
+ */
+export const DEFAULT_LOG_LEVEL = serviceIdentifier<LogLevel>('AzFunctions.DefaultLogLevel');
+
+/**
+ * A logger interface that provides logging methods for different log levels.
+ *
+ * @example
+ * ```ts
+ * @Injectable()
+ * class MyService {
+ *   private readonly logger: Logger;
+ *
+ *   constructor(@Inject(LOGGER_FACTORY) loggerFactory: LoggerFactory) {
+ *     this.logger = loggerFactory('MyService');
+ *   }
+ *
+ *   doSomething() {
+ *     this.logger.info('Doing something...');
+ *   }
+ * }
+ * ```
+ */
+export type Logger = Pick<winston.Logger, LogLevel>;
+
+/**
+ * A prefix for all system loggers used by the AzFunctions platform. This prefix is used to identify loggers that are part of the platform's internal logging system.
+ */
+export const SYSTEM_LOGGER_NAME_PREFIX = '#az-functions';
+export const LOGGER_PROVIDER = serviceIdentifier<LoggerProvider>('AzFunctions.LoggerProvider');
+
+/**
+ * An IoC container identifier for a service that provides log levels for loggers.
+ *
+ * This service can be used to determine the log level for a specific logger based on its name.
+ *
+ * @example
+ * ```ts
+ * @Injectable()
+ * class MyLogLevelProvider implements LogLevelProvider {
+ *   getLogLevel(loggerName?: string): LogLevel | undefined {
+ *     if (loggerName?.startsWith('MyService')) {
+ *       return 'debug';
+ *     }
+ *     return undefined;
+ *   }
+ * }
+ * ...
+ * export const LoggerModule = new ContainerModule(({ bind }) => {
+ *   ...
+ *   bind(LOG_LEVEL_PROVIDER).to(MyLogLevelProvider);
+ *   ...
+ * });
+ * ...
+ * startPlatform({
+ *   ...
+ *   modules: [
+ *     ...
+ *     LoggerModule,
+ *     ...
+ *   ],
+ * });
+ * ```
+ */
+export const LOG_LEVEL_PROVIDER = serviceIdentifier<LogLevelProvider>('AzFunctions.LogLevelProvider');
+
+/**
+ * An identifier for a logger factory function that creates a logger instance.
+ *
+ * @param loggerName - The name of the logger. If not provided, the logger name will be derived from the call stack.
+ * @returns A logger instance.
+ *
+ * @example
+ * ```ts
+ * @Injectable()
+ * class MyService {
+ *   private readonly logger: Logger;
+ *
+ *   constructor(@Inject(LOGGER_FACTORY) loggerFactory: LoggerFactory) {
+ *     this.logger = loggerFactory('MyService');
+ *   }
+ *
+ *   doSomething() {
+ *     this.logger.info('Doing something...');
+ *   }
+ * }
+ * ```
+ */
+export const LOGGER_FACTORY = serviceIdentifier<LoggerFactory>('AzFunctions.LoggerFactory');
+
+/**
+ * A factory function that creates a logger instance.
+ *
+ * @param loggerName - The name of the logger. If not provided, the logger name will be derived from the call stack.
+ * @returns A logger instance.
+ */
+export type LoggerFactory = (loggerName?: string) => Logger;
+
+/**
+ * A IoC container identifier for a function that provides a logger name based on the call stack.
+
+@example
+```ts
+export const LoggerModule = new ContainerModule(({ bind }) => {
+  ...
+  bind(LOGGER_NAME_PROVIDER).toFactory(() => {
+    const regexp =
+      /^\s*at\s+(?:new\s+)?([A-Za-z0-9_$]+)\s+\(.*packages[\\/]examples[\\/]backend[\\/]src[\\/](.+)\/[^\\/]+:\d+:\d+\)$/;
+    return (stackEntry?: string) => {
+      const stackLines = stackEntry?.split('\n') ?? [];
+      let callerLine = stackLines.shift();
+      while (callerLine !== undefined) {
+        const match = regexp.exec(callerLine.trim());
+        if (match !== null) {
+          return `${LOGGER_NAME_PREFIX}.${match[2]?.replace(/\//g, '.')}.${match[1]}`;
+        } else {
+          callerLine = stackLines.shift();
+        }
+      }
+    };
+    ...
+  });
+  ...
+
+  startPlatform({
+    ...
+    modules: [
+      ...
+      LoggerModule,
+      ...
+    ],
+  });
+});
+```
+ */
+export const LOGGER_NAME_PROVIDER = serviceIdentifier<LoggerNameProvider>('AzFunctions.LoggerNameProvider');
+
+/**
+ * A function that provides a logger name based on the call stack.
+ *
+ * @param stackEntry - An optional stack entry from which to derive the logger name.
+ * @returns A logger name or undefined if it cannot be derived.
+ */
+export type LoggerNameProvider = (stackEntry?: string) => string | undefined;
+
+/**
+ * An interface for a service that provides log levels for loggers.
+ *
+ * This service can be used to determine the log level for a specific logger based on its name.
+ *
+ * @example
+ * ```ts
+ * @Injectable()
+ * class MyLogLevelProvider implements LogLevelProvider {
+ *   getLogLevel(loggerName?: string): LogLevel | undefined {
+ *     if (loggerName?.startsWith('MyService')) {
+ *       return 'debug';
+ *     }
+ *     return undefined;
+ *   }
+ * }
+ * ```
+ */
+export interface LogLevelProvider {
+  /**
+   * Gets the log level for a specific logger based on its name.
+   *
+   * @param loggerName - The name of the logger for which to get the log level.
+   * @returns The log level for the specified logger, or undefined if no specific log level is set and default log level should be used.
+   */
+  getLogLevel(loggerName?: string): LogLevel | undefined;
+}
+
+/**
+ * Configuration options for OpenTelemetry (Otel) logging.
+ *
+ * This interface defines the configuration options required to set up OpenTelemetry logging in an application.
+ * It includes the connection string for Application Insights, as well as optional service metadata such as name, instance ID, and version.
+ *
+ * @param applicationInsightsConnectionString - The connection string for Application Insights, used to send telemetry data.
+ * @param serviceName - (Optional) The name of the service being monitored. This is used to identify the service in telemetry data.
+ * @param serviceInstanceId - (Optional) A unique identifier for the specific instance of the service. This can be used to differentiate between multiple instances of the same service.
+ * @param serviceVersion - (Optional) The version of the service being monitored. This can be used to track changes and updates to the service over time.
+ *
+ * @example
+ * ```ts
+ * const otelConfiguration: OtelConfiguration | undefined =
+ *   process.env.APPLICATIONINSIGHTS_CONNECTION_STRING !== undefined
+ *     ? {
+ *         applicationInsightsConnectionString: process.env.APPLICATIONINSIGHTS_CONNECTION_STRING,
+ *         serviceName: process.env.WEBSITE_DEPLOYMENT_ID,
+ *         serviceVersion: '1.0.0',
+ *         serviceInstanceId: process.env.WEBSITE_INSTANCE_ID,
+ *       }
+ *     : undefined;
+ * ...
+ * startPlatform({
+ *   ...
+ *   loggerConfiguration: {
+ *     otelConfiguration,
+ *   },
+ * });
+ * ```
+ */
+export interface OtelConfiguration {
+  applicationInsightsConnectionString: string;
+  serviceName?: string;
+  serviceInstanceId?: string;
+  serviceVersion?: string;
+}
+
+export interface LoggerConfiguration {
+  defaultLogLevel?: LogLevel;
+  otelConfiguration?: OtelConfiguration;
+}
+
+export interface PlatformLogInfo {
+  level: LogLevel;
+  timestamp: Date;
+  message: string;
+  invocationId?: string;
+  traceContext?: TraceContext;
+  operationName?: string;
+  loggerName: string;
+  metadata?: AnyValueMap;
+}