Zongsoft.Diagnostics 1.9.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, together with the Prometheus metric exporter.

Use driver="telemetry" for OTLP export. Set server to the receiver endpoint and protocol to grpc or HttpProtobuf; the endpoint must accept the selected OTLP transport.

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.