ProAuth Documentation

Appearance

Monitoring ​

ProAuth provides comprehensive observability capabilities through integration with modern monitoring systems via OpenTelemetry standards. This allows you to collect and analyze metrics, logs, and traces from your ProAuth deployment, giving you deep insights into performance, errors, and system behavior.

Overview ​

The observability features in ProAuth are built on OpenTelemetry, a Cloud Native Computing Foundation (CNCF) project that provides vendor-agnostic APIs, libraries, and agents for collecting telemetry data. OpenTelemetry supports multiple backend systems, making it easy to integrate ProAuth with your existing monitoring infrastructure.

ProAuth supports the following telemetry types:

  • Logs: Application log data for debugging and analysis
  • Metrics: Quantitative data about application performance and resource usage
  • Traces: Distributed tracing data to track request flows across services

Configuration ​

Observability settings can be configured in the Helm charts for both ProAuth and ProAuth Admin App. The following section describes the available configuration options.

Helm Chart Configuration ​

The observability section in the values.yaml file controls how telemetry data is collected and exported:

yaml
observability:
  # The name of the service being observed.
  serviceNameProAuthCore: ProAuth
  serviceNameProAuthUserStoreWorker: ProAuthUserStoreWorker
  serviceNameProAuthDbDeploymentJob: ProAuthDbDeploymentJob
  
  # Type of exporter to use for tracing. Supported values: "zipkin", "otlp", "console", "none".
  useTracingExporter: none

  # Type of exporter to use for metrics. Supported values: "prometheus", "otlp", "console", "none".
  useMetricsExporter: none

  # Type of exporter to use for logs. Supported values: "console", "otlp", "jsonconsole".
  useLogExporter: jsonconsole

  # Defines how histograms aggregate data. Supported values: "explicit", "exponential".
  histogramAggregation: explicit
  
  # Whether or not to enable instrumentation for sql client.
  enableSqlClientFrameworkInstrumentation: false

  # Whether or not to enable instrumentation for Entity Framework.
  enableEntityFrameworkInstrumentation: false

  # Whether or not to enable instrumentation for Redis.
  enableRedisInstrumentation: false
  
  # Whether or not to enable instrumentation for ASP.NET Core
  enableAspNetCoreInstrumentation: false
  
  # Whether or not to enable instrumentation for HTTP client
  enableHttpClientInstrumentation: false

  # Defines the sampling strategy. Supported values: "AlwaysOnSampler", "AlwaysOffSampler", "TraceIdRatioBasedSampler".
  samplerType: AlwaysOffSampler

  # Ratio for sampling when using "TraceIdRatioBasedSampler". Value between 0 and 1.
  samplingRatio: 0.1
  
  zipkinExporter:
    # Endpoint for the Zipkin exporter.
    endpoint: http://zipkin:9411/api/v2/spans

  otlpExporter:
    # Endpoint for the OTLP exporter.
    endpoint: http://otel-collector:4317

  aspNetCoreInstrumentation:
    # Whether or not to record exceptions in the instrumentation.
    recordException: true

  logLevels:
    # Default log level. Supported values: "Trace", "Debug", "Information", "Warning", "Error", "Critical", "None".
    default: Warning

    # Log level filters for specific namespaces or categories.
    filters:
      Microsoft: Error
      System: Warning

Service Names ​

You can customize the service names for different components of ProAuth:

  • serviceNameProAuthCore: Name for the main ProAuth service
  • serviceNameProAuthUserStoreWorker: Name for the User Store Worker service
  • serviceNameProAuthDbDeploymentJob: Name for the Database Deployment Job

The following service names can be defined for ProAuth Admin App:

  • serviceNameProAuthAdminApp: Name of the admin application service
  • serviceNameProAuthAdminAppDeploymentJob: Name of the UI configuration job service

These names will appear in your monitoring tools, making it easier to identify and filter telemetry data.

Exporters ​

ProAuth supports multiple exporters for different telemetry types:

Tracing Exporters (useTracingExporter) ​

  • otlp: OpenTelemetry Protocol (recommended)
  • zipkin: Zipkin distributed tracing system
  • console: Output traces to the console for debugging
  • none: Disable tracing (default)

Metrics Exporters (useMetricsExporter) ​

  • otlp: OpenTelemetry Protocol (recommended)
  • prometheus: Expose metrics in Prometheus format
  • console: Output metrics to the console for debugging
  • none: Disable metrics collection (default)

Logs Exporters (useLogExporter) ​

  • otlp: OpenTelemetry Protocol (recommended)
  • console: Plain text console output
  • jsonconsole: Structured JSON console output (default)

Instrumentation Options ​

ProAuth can automatically instrument various components to generate telemetry data:

  • enableSqlClientFrameworkInstrumentation: Collect telemetry from SQL client operations
  • enableEntityFrameworkInstrumentation: Collect telemetry from Entity Framework operations
  • enableRedisInstrumentation: Collect telemetry from Redis operations
  • enableAspNetCoreInstrumentation: Collect telemetry from ASP.NET Core operations
  • enableHttpClientInstrumentation: Collect telemetry from HTTP client operations

All instrumentation options are disabled by default. Enable them based on your monitoring needs and the components you're using.

Sampling and Aggregation ​

For tracing, you can configure the sampling strategy:

  • samplerType: Choose between AlwaysOnSampler (100% sampling), AlwaysOffSampler (0% sampling), or TraceIdRatioBasedSampler (percentage-based sampling)
  • samplingRatio: When using TraceIdRatioBasedSampler, this specifies the percentage of traces to sample (0.1 = 10%)

For metrics, you can configure histogram aggregation:

  • histogramAggregation: Choose between explicit (default) or exponential bucket allocation methods

Exporter Endpoints ​

For exporters that send data to external systems, you can configure the endpoints:

  • zipkinExporter.endpoint: The URL for the Zipkin server
  • otlpExporter.endpoint: The URL for the OpenTelemetry Collector

Log Levels ​

You can configure the logging verbosity:

  • logLevels.default: The default log level for all categories
  • logLevels.filters: Specific log levels for named categories (e.g., Microsoft, System)

Available log levels (from least to most verbose): None, Critical, Error, Warning, Information, Debug, Trace

For production environments, we recommend using the OpenTelemetry Protocol (OTLP) for all telemetry types and connecting to an OpenTelemetry Collector, which can then distribute the data to your preferred monitoring backends:

yaml
observability:
  serviceNameProAuthCore: ProAuth
  useTracingExporter: otlp
  useMetricsExporter: otlp
  useLogExporter: otlp
  enableSqlClientFrameworkInstrumentation: true
  enableEntityFrameworkInstrumentation: true
  enableRedisInstrumentation: true
  enableAspNetCoreInstrumentation: true
  enableHttpClientInstrumentation: true
  samplerType: TraceIdRatioBasedSampler
  samplingRatio: 0.1
  otlpExporter:
    endpoint: http://otel-collector:4317
  logLevels:
    default: Information

If your environment does not support OTLP, alternative configurations are available:

  • For logs: Use jsonconsole or console
  • For traces: Use zipkin or console
  • For metrics: Use prometheus to expose a metrics endpoint

OpenTelemetry Collector ​

To fully leverage the observability capabilities of ProAuth, we recommend deploying an OpenTelemetry Collector alongside your ProAuth installation. The collector can receive telemetry data via OTLP and forward it to multiple backend systems.

Here's a sample configuration for the OpenTelemetry Collector that forwards data to Prometheus and Jaeger:

yaml
receivers:
  otlp:
    protocols:
      grpc:
        endpoint: 0.0.0.0:4317
      http:
        endpoint: 0.0.0.0:4318

processors:
  batch:
    timeout: 1s
    send_batch_size: 1024

exporters:
  prometheus:
    endpoint: 0.0.0.0:8889
  jaeger:
    endpoint: jaeger:14250
    tls:
      insecure: true
  logging:
    verbosity: detailed

service:
  pipelines:
    traces:
      receivers: [otlp]
      processors: [batch]
      exporters: [jaeger, logging]
    metrics:
      receivers: [otlp]
      processors: [batch]
      exporters: [prometheus, logging]
    logs:
      receivers: [otlp]
      processors: [batch]
      exporters: [logging]

You can deploy the OpenTelemetry Collector using its Helm chart.

Monitoring Systems Integration ​

With the OpenTelemetry Collector in place, you can integrate ProAuth with various monitoring systems:

  • Metrics: Prometheus, Grafana, Datadog, New Relic
  • Logs: Elasticsearch, Loki, Splunk, CloudWatch
  • Traces: Jaeger, Zipkin, Tempo, X-Ray

The specific integration details will depend on your chosen monitoring stack.

Troubleshooting ​

If you're not seeing telemetry data in your monitoring systems:

  1. Ensure that the exporters are properly configured in the values.yaml file
  2. Verify that the endpoints for external systems are correct and accessible
  3. Check the logs of the ProAuth pods for any errors related to telemetry export
  4. If using the OpenTelemetry Collector, check its logs for connection or configuration issues

For logs, you can temporarily increase the log level to Debug or Trace to get more detailed information about what's happening in the system.