Atya.Diagnostics.OpenTelemetry 1.0.1

Atya.Diagnostics.OpenTelemetry

Atya.Diagnostics.OpenTelemetry is the host-facing OpenTelemetry integration package for Atya diagnostics libraries. It wires OpenTelemetry logging, tracing, and metrics, Atya service identity, resource metadata, optional instrumentations, and OTLP export through one dependency-injection entry point.

Supported Framework

This package intentionally targets net10.0 only. Consumers must run on .NET 10 or a compatible later runtime selected by the .NET host.

Installation

dotnet add package Atya.Diagnostics.OpenTelemetry

Quick Start

using Microsoft.Extensions.DependencyInjection;
using OpenTelemetry.Exporter;

services.AddAtyaOpenTelemetry(options =>
{
    options.Observation.ServiceName = "Orders.Service";
    options.Observation.ServiceVersion = "1.0.0";
    options.EnableLogging = true;
    options.ActivitySources.Add("Orders.Workflows");
    options.Meters.Add("Orders.Business");

    options.Resource.ServiceNamespace = "orders";
    options.Resource.DeploymentEnvironment = "production";

    options.Instrumentations.AspNetCore.Enabled = true;
    options.Instrumentations.HttpClient.Enabled = true;
    options.Instrumentations.SqlClient.Enabled = true;
    options.Instrumentations.SqlClient.CaptureSqlText = false;
    options.Instrumentations.EntityFrameworkCore.Enabled = true;
    options.Instrumentations.EntityFrameworkCore.CaptureSqlText = false;
    options.Instrumentations.GrpcClient.Enabled = true;
    options.Instrumentations.Runtime.Enabled = true;

    options.Exporters.Console.Enabled = true;
    options.Exporters.Otlp.Enabled = true;
    options.Exporters.Otlp.Endpoint = "http://otel-collector:4317";
    options.Exporters.Otlp.Protocol = OtlpExportProtocol.Grpc;
});

Configuration Binding

Bind from the default OpenTelemetry configuration section:

{
  "OpenTelemetry": {
    "Observation": {
      "ServiceName": "Orders.Service",
      "ServiceVersion": "1.0.0"
    },
    "EnableLogging": true,
    "EnableTracing": true,
    "EnableMetrics": true,
    "EnableObservationLogging": false,
    "ActivitySources": [ "Orders.Workflows" ],
    "Meters": [ "Orders.Business" ],
    "Resource": {
      "ServiceNamespace": "orders",
      "DeploymentEnvironment": "production",
      "Attributes": {
        "team": "platform"
      }
    },
    "Logging": {
      "IncludeFormattedMessage": true,
      "IncludeScopes": true,
      "ParseStateValues": true
    },
    "Instrumentations": {
      "AspNetCore": { "Enabled": true },
      "HttpClient": { "Enabled": true },
      "SqlClient": {
        "Enabled": true,
        "CaptureSqlText": false
      },
      "EntityFrameworkCore": {
        "Enabled": true,
        "CaptureSqlText": false
      },
      "GrpcClient": { "Enabled": true },
      "Runtime": { "Enabled": true }
    },
    "Exporters": {
      "Console": {
        "Enabled": true
      },
      "Otlp": {
        "Enabled": true,
        "Endpoint": "http://otel-collector:4317",
        "Protocol": "Grpc",
        "Headers": {
          "x-service": "orders"
        }
      }
    }
  }
}

services.AddAtyaOpenTelemetry(configuration);

Use a custom section when needed:

services.AddAtyaOpenTelemetry(configuration, "Diagnostics:OpenTelemetry");

Behavior

• Observation.ServiceName is required and is trimmed before registration.
• Observation.ActivitySourceName defaults to Observation.ServiceName when omitted.
• Observation.MeterName defaults to Observation.ServiceName when omitted.
• ActivitySources adds extra application ActivitySource names beyond the package default.
• Meters adds extra application Meter names beyond the package default.
• Options passed to AddAtyaOpenTelemetry are validated immediately because the OpenTelemetry providers are configured during service registration.
• Configure the package through the delegate or configuration section passed to AddAtyaOpenTelemetry; later services.Configure<OpenTelemetryOptions>(...) calls do not rebuild the OpenTelemetry logging, tracing, or metrics providers.
• Tracing and metrics are enabled by default.
• OpenTelemetry logging is disabled by default. Set EnableLogging to true to register the OpenTelemetry logging provider and export logs through configured exporters.
• Observation-layer logging is disabled by default.
• EnableObservationLogging registers Atya Observation logging services; it does not by itself register the OpenTelemetry logging provider.
• ASP.NET Core, HttpClient, Runtime, console exporter, and OTLP exporter registrations are opt-in.
• SqlClient, Entity Framework Core, and gRPC client instrumentations are opt-in.
• SQL command text capture is disabled by default because command text can contain sensitive data.
• The package composes Atya.Diagnostics.Observation; it does not define business metrics, activity names, or log catalogs.

Validation and Errors

Options are validated through Microsoft.Extensions.Options. Invalid options fail when options are resolved or when host startup validation runs.

• Observation.ServiceName cannot be null, empty, or whitespace.
• ActivitySources and Meters cannot contain null, empty, or whitespace names.
• OTLP Endpoint, when set, must be an absolute URI.
• OTLP Protocol, when set, must be a defined OtlpExportProtocol value such as Grpc or HttpProtobuf.
• OTLP header names cannot be empty and cannot contain , or =.
• OTLP header values cannot be null and cannot contain ,.

Supported Instrumentations

SQL command text capture is controlled separately:

Leave SQL text capture disabled unless queries are known not to contain secrets or regulated data and telemetry access is appropriately restricted.

Supported Exporters

Package Boundaries

Compatibility and Versioning

The package follows semantic versioning. Breaking public API or behavior changes require a major version. Release versions use stable SemVer such as 1.0.0.

Runtime dependencies are centrally managed by the repository. Consumers should keep their own OpenTelemetry and Microsoft.Extensions package set coherent, especially in applications that already reference OpenTelemetry packages directly.

Entity Framework Core and gRPC client instrumentation currently depend on upstream OpenTelemetry prerelease instrumentation packages. They are included intentionally in the stable 1.0.0 package line and should be reviewed during dependency updates.

Support and Security

Use the repository issue templates for bug reports and feature requests. Report security issues privately according to the repository SECURITY.md; do not disclose suspected vulnerabilities in public issues.

Migration Notes

This is the initial 1.x package line. Future migrations will be documented in the repository CHANGELOG.md with any required code or configuration changes.