mirror of
https://github.com/OPCFoundation/UA-.NETStandard.git
synced 2026-10-26 04:19:53 +08:00
f6b27025a6
## Proposed changes Fixes #4857. The stack's log messages wrote network addresses (endpoint, discovery and reverse connect URLs, host names, IP addresses, ports), application and user identities, file paths and exception texts as plain parameters. Applications had no reliable way to keep them out of general-purpose logs. This PR replaces the stack's own redaction mechanism with the standard .NET [data classification and redaction](https://learn.microsoft.com/dotnet/core/extensions/data-redaction) packages. Each sensitive `[LoggerMessage]` parameter is classified. The application decides per classification what reaches its logs: erase it, replace it with an HMAC token so entries stay correlatable, or pass it through. ### Taxonomy `Opc.Ua.Redaction.OpcUaDataClassifications` defines the `OpcUa` taxonomy and one attribute per classification: | Classification | Used for | Parameters | |---|---|---| | `[NetworkAddress]` | URLs, host and domain names, IP/MAC addresses, end points, ports | 120 | | `[ApplicationIdentity]` | certificates, subject, issuer, thumbprint, ApplicationUri | 103 | | `[FilePath]` | file, directory and certificate store paths | 67 | | `[SensitiveText]` | exception or remote-supplied text passed as a parameter | 55 | | `[UserIdentity]` | user names, token subjects | 7 | Correlation ids (`ChannelId`, `SessionId`, ...), status codes and NodeIds stay unclassified. ### Pipeline and defaults - Opc.Ua.Core now references `Microsoft.Extensions.Telemetry(.Abstractions)` 10.11.0, so every project above Core uses the `Microsoft.Gen.Logging` generator. Opc.Ua.Client already did, through Http.Resilience. The packages ship net462 and netstandard2.0 builds, so net48 is supported. - **A plain `ILoggerFactory` logs `(null)` in place of classified values.** Classified values are only written by the redaction-aware logger. - The new `ILoggingBuilder.EnableOpcUaRedaction()` turns that logger on. It is `EnableRedaction()` with the discriminator off; otherwise every unredacted value gets `:ParamName` appended. `AddOpcUa().AddLogging(...)` and `DefaultTelemetry.Create(...)` call it, as do the samples, so they log the same information as before until redactors are registered. - `services.AddOpcUa()` alone does not change the host's logging. Generic-host apps call `builder.Logging.EnableOpcUaRedaction()`. This is documented as a behavior-breaking change in `docs/migrate/2.0.x/telemetry.md`. ### Obsolete API `Redact`, `RedactionWrapper<T>`, `IRedactionStrategy`, `RedactionStrategies` and `SimpleRedactionStrategy` are `[Obsolete]`. They still work, but the stack no longer uses them. ### Not classified - The `Exception` passed to a log call. Applications can drop exception messages with `LoggerEnrichmentOptions.IncludeExceptionMessage`. - Exception and `ServiceResult` message texts. - `ServiceResult`/`StatusCode` parameters and logged data values. - The few log calls whose level is decided at run time. - `Opc.Ua.Vision.OpenUsd`, which references only Opc.Ua.Types and cannot see the attributes. ### Generator behavior differences These are visible to log consumers and to tests: - `IFormattable` values such as `NodeId` are stored in the structured state as invariant strings, not as objects. - The generated log state is a thread-local object that is cleared after the call. - Classified values are pooled redactor objects, valid only during the `Log` call. Tests that inspected log state after the fact now capture it during the call. The shared `RecordingLoggerProvider` snapshots classified values. ## Related Issues - Fixes #4857 ## Types of changes - [ ] Bugfix (non-breaking change which fixes an issue) - [x] Enhancement (non-breaking change which adds functionality) - [ ] Test enhancement (non-breaking change to increase test coverage) - [x] Breaking change (fix or feature that would cause existing functionality to not work as expected; plain logger factories drop classified values) - [x] Documentation Update (if none of the other choices apply) ## Checklist - [x] I have read the CONTRIBUTING doc. - [x] I have signed the CLA. - [x] I ran tests locally with my changes, all passed. - [x] I fixed all failing tests in the CI pipelines. - [x] I fixed all introduced issues with CodeQL and LGTM. - [x] I have added tests that prove my fix is effective or that my feature works and increased code coverage. - [x] I have added necessary documentation (if appropriate). - [ ] Any dependent changes have been merged and published in downstream modules. ## Further comments New tests: - `LogClassificationCoverageTests` (Tools.Tests) scans all 104 stack assemblies and fails if an address, identity or path parameter of a `[LoggerMessage]` method is unclassified. - `DataClassificationLoggingTests` (Core.Tests) pins erasing and HMAC redaction, pass-through, the plain-factory drop, and both stack defaults. Local results on net10.0: | Suite | Passed | Failed | |---|---|---| | Core.Tests | 6,489 | 0 | | Client.Tests | 3,231 | 0 | | Tools.Tests | 7,210 | 0 | | PubSub.Tests | 1,536 | 0 | | Core.Diagnostics.Tests | 571 | 0 | | Configuration.Tests | 241 | 0 | - **Server.Tests:** the full run predates the final test fixes and had 12 failures. All 12 were in the fixtures fixed afterwards, which now pass: RoleStateBinding (45/45) and the FileDirectory and compatibility-logging fixtures (74/74 in total). The full Core.Tests and Server.Tests runs were not repeated after those fixes. - **Builds:** `UA.slnx` builds with 0 errors for net10.0 and net48, and the whitespace check passes. - **NativeAOT:** not confirmed locally, because the machine has no C++ linker. A trimmed publish of `Opc.Ua.Aot.Tests` reported no trim or AOT warnings from the stack, the new packages or the generated logging code; its only errors come from the TUnit test framework (`FSharp.Core` not found). The `aot-test` CI job has to confirm the native build. 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com> Co-authored-by: Marc Schier <marcschier@users.noreply.github.com>
OPC 40001 Machinery samples
Two console applications that show the whole OPC 40001 series end to end.
| Sample | What it does |
|---|---|
| MachineryServer | Serves one simulated hydraulic press with every part of the series |
| MachineryClient | Walks the Machines folder, prints what it finds, downloads a result and streams state |
Run them in two terminals:
dotnet run --project samples/Machinery/MachineryServer -- --port 62546
dotnet run --project samples/Machinery/MachineryClient -- --insecure
The client prints something like:
Machine 12:HydraPress-1 (ns=12;i=1)
Acme Machine Tools HydraPress 500 — serial HP500-2024-0001
location: Hall 3 / Line 2
state: Executing / mode: Processing
component 12:HydraulicUnit
building block 13:Identification
building block 3:MachineryEquipment
building block 8:JobManagement
building block 3:Monitoring
building block 3:MachineryItemState
building block 3:Notifications
building block 13:OperationCounters
building block 3:MachineryOperationMode
building block 3:Components
device health: NORMAL
operation counters: power-on 12480.0 h, operating 9215.5 h
equipment UpperDie (urn:acme-machine-tools.example:equipment:die)
life: 118400 of 250000 left
process value HydraulicOilTemperature: 44.0 °C (setpoint 45.0, 45.7 % of range)
limits: 5.0 / 15.0 / 65.0 / 80.0
energy CompressedAir: Main = HydraPress-1/CompressedAir
NeEnergyImportHp = 0
NeEnergyExportHp = 0
Volume = 184320
VolumeFlowRate = 18.4
Pressure = 620000
Temperature = 294.65
energy Electricity: Main = HydraPress-1/Electricity
AcActivePowerTotal = 41250
Latest result: stroke-000019
downloaded 42 bytes:
resultId,stroke-000019
peakForceKN,4703.6
Observing MachineryItemState for 4s (OPC 40001-1 state changes always come from the server) …
22:33:52 -> Executing (via FromNotExecutingToExecuting)
22:33:52 -> NotExecuting (via FromExecutingToNotExecuting)
The namespace indices above are whatever the server happened to assign; only
the browse names are stable. 2:Identification and 2:OperationCounters show
up as 13: because OPC 40001-1 gives both the Device Integration namespace —
see Default instance browse names are
load-bearing.
The building blocks come from the OPC 40001-1 MachineryBuildingBlocks
organizer, which is the one place a client can discover what a machine
supports instead of probing for each block in turn. The oil temperature walks a
slow ramp across the datasheet limits, so the exclusive limit alarm on the
process value activates and clears while the sample runs; subscribe to
HydraulicOilTemperature to watch it.
What the sample does not need a second terminal for is the same walk as an
automated test: MachineryEndToEndTests runs this server and this client over
opc.tcp inside the test suite.
See the Machinery developer guide.