Zongsoft.Diagnostics 1.14.0

Zongsoft.Diagnostics Diagnostics Plugin Library

English | 简体中文

Overview

Zongsoft.Diagnostics is the diagnostics plugin library for the Zongsoft open-source framework. It provides diagnostics and telemetry features based on OpenTelemetry.

The Zongsoft.Diagnostics.option configuration file defines the default OpenTelemetry metric and trace exporters.

Use driver="opentelemetry" for OTLP export. Set server to the receiver endpoint and protocol to grpc or HttpProtobuf; the endpoint must accept the selected OTLP transport. The bundled Diagnostics receiver uses /opentelemetry, so its paired exporter configuration uses server=http://localhost:4317/opentelemetry;protocol=grpc. Official SDK exporters use this full endpoint directly; direct generated clients use the client base-path handler.

Enable or disable exporters

The code entry points are Zongsoft.Diagnostics.Telemetry.ExporterLauncher.Default (OTLP) and ExporterLauncher.Console. Both expose Meters, Tracers, and Logs launcher instances. The host discovers them through assembly scanning; configuration uses driver="opentelemetry" or driver="opentelemetry.console". The private registration class in ExporterLauncher.cs connects logging automatically.

Each metric or trace exporter accepts enabled="true|false". Omission defaults to true, preserving existing configurations. enabled="false" excludes that exporter before driver resolution and provider construction, so disabled exporters do not require a registered driver or parse their connection settings. If every exporter for a signal is disabled, its provider is not created. The XML and its boolean values must still be valid configuration.

For example, retain a shared OTLP declaration in Web configuration while disabling its metric export:

<exporter exporter.name="telemetry" driver="opentelemetry" enabled="false"
	settings="server=http://127.0.0.1:4317;protocol=grpc;" />

This switch is independent for metrics and traces. The Web plugin can still contribute an enabled Prometheus exporter to the same metrics configuration.

Strongly typed exporter settings

settings remains semicolon-delimited text. The string contracts of FilteringExporter.Settings and IExporterLauncher.Launch are unchanged. Internally, launchers use ExporterLauncherSettingsDriver to create typed settings, with SDK option projection kept in Telemetry/ExporterLauncher.cs.

Both settings types live in Zongsoft.Diagnostics.Configuration and independently inherit the connection-settings base; Console does not inherit OTLP properties. Private drivers expose instances through typed public interfaces. The .plugin explicitly registers both under /Workbench/Configuration/ConnectionSettings/Drivers, without relying on discovery of an Instance member. Direct API calls need no plugin host:

var settings = ExporterLauncherSettingsDriver.Default.GetSettings(
	"server=http://localhost:4317;protocol=grpc;timeout=30s;interval=5s;");
var consoleSettings = ExporterLauncherSettingsDriver.Console.GetSettings(
	"target=Console,Debug;interval=10s;");

Keys are case-insensitive. Durations support connection-settings formats such as 1500ms and 5s; typed defaults are not inserted into the original Value. Unknown keys remain in the dictionary, following the base settings contract; they do not add exporter behavior.

An absent or entirely empty settings leaves SDK defaults and environment configuration untouched. The defaults above apply to omitted parameters in nonempty settings text. Invalid typed values read by an enabled exporter now fail rather than silently using defaults. Projection also validates enums, absolute HTTP/HTTPS endpoints, durations between 1 and 2147483647 milliseconds, positive batch/queue sizes, and maxBatchSize <= maxQueueSize. An explicitly empty server is invalid. The existing OTLP projection reads processor and batch settings for all three signals; they only control log/trace processing. Console logs and traces read only target, ignoring metric-only timing parameters. Disabled exporters do not parse settings.

New configuration uses opentelemetry and opentelemetry.console. Launchers continue accepting the case-insensitive aliases telemetry, OpenTelemetry, and Console; OTLP also retains empty-driver matching. exporter.name="telemetry" is the configuration entry name, distinct from its driver. Existing host variables and switches under diagnostics.telemetry and diagnostics.logging retain their names.

Zongsoft.Net telemetry sources

The TCP library exposes a BCL Meter and ActivitySource named Zongsoft.Net without creating providers or exporters. Explicitly include that name in the existing Meters/filter and Traces/filter, preserving other required sources and exporters. A bare * expands predefined sources and application modules; it does not subscribe to every library. See the Net telemetry contract for instruments, units, and trace boundaries. The host decides whether fault events become logs and can use the Microsoft ILogger configuration below.

Microsoft ILogger logs

During service registration, the plugin reads /Diagnostics/Diagnostor/Logs and connects Microsoft.Extensions.Logging.ILogger to OpenTelemetry. Hosts need no Program.cs changes or ASP.NET Core dependency. Zongsoft's own Logging/ILogger and Console.WriteLine are outside this pipeline.

Logs are disabled by default. To enable them, place this node inside <diagnostor>:

<logs includeScopes="true" includeFormattedMessage="true">
	<exporters>
		<exporter exporter.name="telemetry" driver="opentelemetry" enabled="true"
			settings="server=http://127.0.0.1:4317;protocol=grpc;processorType=batch;timeout=30s;interval=5s;" />
	</exporters>
</logs>

For local debugging, add a Console log exporter inside <logs><exporters>. It can coexist with an OTLP exporter:

<exporter exporter.name="console" driver="opentelemetry.console" enabled="true" settings="target=Console;" />

The target setting follows the metric and trace Console exporters: it defaults to Console and also supports Debug or Console,Debug. Logs are exported individually; interval, timeout, and batch settings do not apply. This is OpenTelemetry's detailed log output. If the host also enables the standard Console logging provider, the same log may appear twice.

Logging is independent of metrics and tracing. If <logs> is absent, has no exporters, or all exporters have enabled="false", no logging provider is registered. Disabled entries do not resolve drivers or parse settings. A missing enabled driver fails startup with Signal=logs and ExporterDriver in exception Data.

Categories and levels follow standard host Logging:LogLevel settings, including provider-specific Logging:OpenTelemetry:LogLevel rules. There is no additional <filter>. includeScopes and includeFormattedMessage default to true. The SDK exports structured attributes, exceptions and the current Activity's TraceId/SpanId. Startup logs without an Activity normally have no trace identifiers.

The log resource uses IHostEnvironment.ApplicationName (or the current application domain name without a host environment), with OTEL_SERVICE_NAME and OTEL_RESOURCE_ATTRIBUTES overrides. Metrics, traces and logs in the same process share the default service.instance.id. Host DI owns the provider and flushes pending batches on normal disposal; the metric/trace worker does not start or stop logging. Configuration changes require a host restart, and logs written before registration are not replayed. Existing OpenTelemetry dependencies include logging; plugin manifests and deployment dependencies need no ASP.NET Core additions.

The receiver must support OTLP logs. Aspire Dashboard accepts them directly. The existing metrics-only Collector example needs a separate logs pipeline and log backend; Prometheus does not store logs.

General and Web hosts

The common library has no ASP.NET Core dependency. Daemon and terminal deploy only this package, sending OTLP metrics to a Collector that Prometheus scrapes. Direct Web scraping moved to Zongsoft.Diagnostics.Web, deployed only to Web hosts.

A Collector normally accepts server=http://127.0.0.1:4317;protocol=grpc, without the Zongsoft receiver's /opentelemetry prefix. Collector and Prometheus YAML configuration files are read by their respective services. Containers require service names and reachable listening addresses.

The worker sets service.name from the application name; the SDK generates a process service.instance.id shared by metrics and traces. OTEL_SERVICE_NAME and OTEL_RESOURCE_ATTRIBUTES override defaults. A missing enabled exporter fails startup with InvalidOperationException and ExporterDriver/Signal data. Partial startup releases already-created providers.

Build Core first, then run dotnet test test/Zongsoft.Diagnostics.Tests.csproj -p:GeneratePackageOnBuild=false to check the ordinary .NET runtime, exporter registration, resource identity, exported metrics/traces and lifecycle.

Zongsoft.Diagnostics.slnx and the default Cake test task include only unit tests. Protocol integration tests live in separate protocols/client/test/integration and protocols/server/test/integration projects. Each integration project has its own solution in the same directory: client and server. Prepare the dependencies in Local Verification, then run dotnet cake build.cake --target=integration-test from this directory to exercise the local HTTP/2 and OTLP services explicitly.

Bundled OpenTelemetry Protocol

The proto directory is a Git submodule pinned to the upstream OpenTelemetry Protocol repository. It contains the OTLP protocol specification and the corresponding language-independent interface types (.proto files). Keep this submodule clean: protocol documentation and project-specific guidance belong in this README rather than in the upstream working tree.

Language-Independent Interface Types

The Proto files can be consumed as a Git submodule or copied and built directly in a consumer project. OpenTelemetry client libraries publish compiled artifacts to central repositories such as Maven. Changes to the upstream definitions must follow the OpenTelemetry Proto contribution guidelines.

OTLP/JSON

Additional requirements for the OTLP/JSON wire representation are defined by the JSON Protobuf encoding specification.

Generating gRPC Client Libraries

The upstream repository generates raw gRPC client libraries with make gen-${LANGUAGE}. Supported targets currently include:

• cpp
• csharp
• go
• java
• objc
• openapi (Swagger)
• php
• python
• ruby

Maturity

Releases numbered 1.0.0 and later may still contain unstable alpha or beta components, as indicated below.

See Versioning and Stability for the definition of maturity levels.

Stability Guarantees

Components marked Stable guarantee that existing field types, numbers, and names; service and package names; method names, parameters, return types, and invocation kinds; message and enum symbols; package names and directory structure; and existing optional or repeated declarations will not change incompatibly. Existing symbols will not be deleted.

Compatible additive changes may introduce:

• New fields in existing messages.
• New messages or enums.
• New enum choices.
• New choices in existing oneof fields.
• New services.
• New methods in existing services.

Every additive change must explain how senders and receivers implemented against protocol versions from before and after the change interoperate.

Experiments

New experimental components should be isolated in a development subdirectory and use Development, Alpha, Beta, or Release Candidate maturity labels. Experimental components that are not referenced by a stable component may be removed when an experiment ends. Successful experiments require review before they become Stable and inherit the full stability guarantees.

Experimental fields or messages added to stable components must remain compatible and be clearly marked as non-stable. If an experiment is abandoned, those fields or messages must remain in place and may only be deprecated; senders should normally leave them empty, and receivers must continue to tolerate empty values.

Generated Code

The upstream project does not guarantee the stability of code produced by any particular Proto code generator.

Upstream Maintainers and Approvers

• Maintainers: OpenTelemetry Technical Committee
• Approvers: OpenTelemetry Specification Sponsors

See the OpenTelemetry community membership guide for role details.

Plugin-Based Integration

Compose this feature through the host; a package reference supplies compile-time APIs, while plugin loading also requires deployed manifests and runtime assets. See the complete plugin workflow.

The plugin contributes diagnostics configuration and a startup component. Select filters/exporters in its same-stem .option; loading it can activate telemetry exporters, so use controlled destinations.

Add this fragment to an existing host .deploy (retain Main and the host’s other base manifests; do not replace the whole file):

[plugins zongsoft diagnostics]
nuget:Zongsoft.Diagnostics

Run dotnet deploy against a test deployment as explained in the workflow, with the host's framework, platform, architecture and, where needed, site. Pin compatible versions in real deployments; application dependencies such as databases, caches or commercial runtimes are still separate prerequisites.

Additional artifacts listed by the deployment manifest include Zongsoft.Diagnostics.option, Zongsoft.Diagnostics.plugin. Retain assemblies, dependencies and satellite resource directories as well. Restart the host after deployment, check plugin loading and service/driver registration, then verify the workflow above; copied files alone do not prove that the feature is active.