mirror of
https://github.com/OPCFoundation/UA-.NETStandard.git
synced 2026-10-18 14:43:08 +08:00
romanett
28f1401324
Profiling the reference server under load showed most request-path CPU spent spinning on contended locks, plus several avoidable allocations per request or per node. This PR removes them, switches the reference server to Server GC, and adds the load harness used to measure it. ## Results Paired A/B against `master` (3 alternating rounds, medians, 20 sessions, workstation GC on both sides, 24-core machine): | Scenario | Throughput | p50 | p90 | Server CPU / op | Server alloc / op | Lock contention | |---|---|---|---|---|---|---| | Read, 1 value | **+45%** (94k → 137k req/s) | −20% | −46% | −37% | −39% | −94% | | Read, 100 values | **+40%** | −26% | −17% | −24% | −25% | +130% ¹ | | Read, 100 values, SignAndEncrypt | **+48%** | −36% | −20% | −30% | −26% | +106% ¹ | | Browse (Server object) | **+33%** | −31% | −12% | −13% | −14% | −40% | | Write, 100 values | +13% | −12% | −4% | −10% | −19% | −23% | | Data-change subscriptions | ±0 ² | ≈ | ≈ | −14% | −17% | −29% | ¹ The faster server spends more time in the remaining per-node locks. ² Throughput is bounded by the writer rate in this scenario. Separately, Server GC instead of workstation GC doubles Read-100 throughput (21k → 44k req/s) and cuts p90 from 2.1 ms to 0.6 ms, because workstation GC paused the server for about half the wall time under load. The working set grows from ~210 MB to ~430 MB. ## Changes - **`ObjectPool<T>`**: lock-free slot array. `ConcurrentBag.Count` took every per-thread lock on each `Return` of the pooled response value-task source, once per request. - **`FairRequestQueue`**: - drops redundant gate entries: the fail-fast pre-checks and the stopped check read volatile fields and are re-checked under the gate; the owner count is folded into selection; - coalesces wake pulses with a pending flag, so the bounded signal channel's lock is only taken when no token is outstanding. Wake-count semantics in the tests are unchanged. - **`DefaultServerResourceIsolationProvider`**: - compares peer addresses without `GetAddressBytes()` allocations; - builds the unsecured verification context only when a classifier is configured. - **TCP listener / channel**: caches the certificate DER copies per channel, keyed on the certificate instance. `X509Certificate2.RawData` returns a fresh copy on every access, and the listener read it for every request. - **`EndpointBase`**: resolves the request `ActivitySource` once instead of `Assembly.GetCallingAssembly()` per request. - **Node managers**: - one `ServerSystemContext` copy per request (cached on the `OperationContext`) for per-node callbacks: permission metadata, node metadata, view membership, method lookup; - removes a discarded copy in `GetReferenceDescriptionAsync`; - per-request operation caches are plain `Dictionary` instead of a `ConcurrentDictionary` with 24 lock objects; - the validation cache is built in one pass; - fixes zero-capacity error lists. - **`ResourceManager`**: translation lookups read an immutable snapshot that is rebuilt after writes. Browse serialised on the global lock for every display name. - **`MonitoredItem`**: shares the default `DataChangeFilter` instead of allocating one per sampled value. - **Reference server**: `ServerGarbageCollection=true`; new "Garbage collector mode" section in `docs/ServerScalability.md`. - **`perf/`**: `ServerLoadHarness` (out-of-process server plus load driver, server-side CPU/GC/alloc/contention deltas, optional `dotnet-trace` capture), `TraceAnalyzer` (TraceEvent-based CPU/allocation/contention aggregation), and paired A/B scripts. Not part of `UA.slnx`. ### Behaviour notes for custom node managers - The `IDictionary<NodeId, NodeState>` operation cache handed to overrides is now a `Dictionary`. It was a `ConcurrentDictionary`, but only one request flow uses it. - Within one request, per-node callbacks of a node manager share one `ServerSystemContext` copy. ### Later commits on this PR - **Permission checks without `NodeMetadata`** (`9068684c3`): the role-permission and access-restriction validators run on an internal `PermissionMetadata` struct; `AsyncCustomNodeManager` fills it on the stack from the same attributes and namespace defaults. Browse's reference filter reads 3 attributes per target instead of 13. Read 100 values: 120.6 → 95.7 KB/request, ~21k → 26k req/s; Browse 67.6 → 51.8 KB, 26.7k → 29.8k req/s. - **Read-only channel evidence** (`936b28d76`, `dc638ab9f`): `SecureChannelContext.ClientChannelCertificate`, `ServerChannelCertificate` and `ChannelThumbprint` are `ByteString`, so the cached per-channel certificate buffer is shared without a copy and cannot be altered by handlers or classifiers. **Public API change**, see the new section in `docs/MigrationGuide.md`. The isolation provider's revalidation snapshot still copies. - **Session lookup** (`936b28d76`): `SessionManager.TryGetSessionContext` takes the candidate snapshot without the bindings lock; the validating check under the lock is unchanged (2 instead of 4 global lock acquisitions per request). - Unit tests for `ObjectPool`, the per-request system context cache, the translation snapshot, `SecureChannelContext` null semantics and a stopped `FairRequestQueue`; `perf/` follows the repository conventions. ## Testing - `Opc.Ua.Server.Tests` (net10.0): 8386 passed before the `ByteString` change. After it, 13 secure-session and isolation tests failed; both causes are fixed in `dc638ab9f` and those tests (25 with their variants) pass. A full rerun of the Server, Sessions, Core, Redundancy, LDS and GDS suites on the final commit is in progress. - Full solution builds for net10.0 and net48; `dotnet format whitespace` clean. ### o6-automation opcua-benchmarks (sampling, deep pipelines) Replicated both tests of the [o6-automation benchmark](https://github.com/o6-automation/opcua-benchmarks) in the harness (`--scenario counters`, and `read` with 10 clients × N outstanding), paired against `origin/master`: | Test | master | this PR | |---|---|---| | Subscription sampling, 100 Hz, every item ≥ 99 % of samples, 1 item | FAIL (75–94 %) | PASS (100 %) | | same, 1024 items | FAIL (64–73 %) | PASS (99.9 %) | | same, capacity | — | between 4096 and 6144 items (~410–520k samples/s) | | Read, 10 clients × 100 outstanding, None | stalls (0–1.7k req/s) | 121–131k req/s | | Read, 10 clients × 100 outstanding, SignAndEncrypt | stalls (0 req/s) | 89–91k req/s | | Read, 10 clients × 1000 outstanding | channels faulted (`BadTcpNotEnoughResources`) | 0 errors, ~45–54k req/s | - **Fixed-rate sampling** (`30b769d13`): the sampling loop waited one interval after each sample, adding timer overshoot and sampling time to every cycle; samples now have absolute deadlines. - **Async response send** (`cdac5c5ca`): `SendResponse` blocked thread-pool workers on the channel gate; with many requests in flight the receive loop that was handed the gate waited for a pool thread and the channel stalled. The TCP, Kestrel TCP and WebSocket listeners now use `SendResponseAsync`. - **Backpressure instead of channel fault** (`191cd2ba7`): server channels stop reading while more than 100 responses are queued and resume at 50, instead of faulting the channel. Client channels keep reading. At 10,000 outstanding requests throughput is ~50k req/s with or without the limit engaged, so the remaining gap to the 100-per-client case is not the backpressure. ## Not changed - `SentMessageQueue` deep-clones every `NotificationMessage`. Retained messages return their pooled payloads on acknowledgement while the response copy may still be queued for send, and a client can acknowledge a sequence number before receiving it; the clone keeps a recycled payload from reaching another session's response. Removing it needs a send-completion hook from the transport. - Generated responses allocate a default `ResponseHeader` that is replaced (~2-3 % of per-request allocation). Fixing it means making structure fields of every generated type lazily initialized, a generator-wide change to default values, equality and encoding. 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
OPC UA .NET Standard stack documentation
These guides lead from a first working application to advanced and experimental capabilities. Follow the numbered stages when you are learning. Choose only the paths that match your application, or use the contents list to find a feature.
- New to the SDK? Start with Getting started, read OPC UA concepts, then build your first information model.
- Upgrading from 1.5.x? Read What's New in 2.0, then follow the Migration Guide.
- Contributing to this repository? See Contributing and maintaining the SDK.
Contents
- How to use this index
- 1. Get started
- 2. Build your application
- 3. Add data types and application services
- 4. Use companion models
- 5. Prepare for production
- 6. Advanced integration, reliability, and scale
- 7. Draft and experimental capabilities
- Reference and upgrade
- Contributing and maintaining the SDK
How to use this index
Each stage builds on the earlier ones, but you do not need to read every guide. After stage 1, choose the client, server, or PubSub path. Stages 3 to 7 are optional; use the guides your application needs. A stage or group names the knowledge it assumes.
Labels describe the maturity of a package or model:
- Preview package: the package family keeps a
-previewversion, even when the core packages are stable. See Versioning. - Draft model: the guide implements a working-group draft specification. Its namespace URIs and NodeIds are provisional.
- Experimental: the guide marks the feature as experimental.
These labels are independent of difficulty. An advanced guide can describe a stable feature, and a released specification can ship in a preview package.
1. Get started
Run a client and server, then learn the terms that the other guides use.
- Getting started — run the minimal samples, or build a client and server from NuGet packages.
- OPC UA concepts — applications, endpoints, sessions, the address space, values, subscriptions, and PubSub.
- Your first information model — add a model to the Getting started server, then read, write, and call it from the client.
- Sample catalogue — minimal, reference, PubSub, and companion-model applications.
- Packages and supported platforms — choose packages and target frameworks.
2. Build your application
Choose the path for your application. The paths are independent: for example, a PubSub application needs neither a client nor a server.
Client path
Assumes Getting started.
- Dependency injection: client feature — configure a client in the .NET Generic Host.
- Managed sessions — connect, recover from connection loss, and close. To compare the managed and classic session APIs, see choosing a session API.
- Read, write, and call methods — resolve namespace URIs and browse paths, check the status of each operation, and call methods through a client generated from the model.
- Subscriptions — callback subscriptions for long-lived monitoring and streams for short observations.
Server path
Assumes Getting started.
- Dependency injection: server feature — host a server and configure its endpoints, security, and node managers.
- Node managers: start with a model — generate a node manager from your model and attach callbacks. Your first information model is a complete example.
- Runtime NodeSets — load NodeSet2 models without generated code when models change independently of your application.
- Asynchronous server support — implement service and node-manager callbacks asynchronously.
PubSub path
A PubSub application needs neither a client nor a server, so the Getting started exercise and the other two paths are optional here.
- Concepts: client/server and PubSub — publishers, subscribers, and datasets.
- Run a first publisher and subscriber — exchange signed and encrypted messages on one computer with the reference PubSub sample.
- PubSub guide — the fluent builder, hosting, configuration, encodings, and security.
- Transport selection — UDP, Ethernet, MQTT, and Kafka.
3. Add data types and application services
Assumes the client or server path. Choose the capabilities your application needs.
Data types and models
- Source-generated data types — generate encodeable implementations for your own structures.
- Complex types — decode server-defined structures and enumerations at run time.
- Model dependencies — compose models that depend on other models.
- NodeId assignment — control the identifiers of nodes created at run time.
- Schema generation — produce XSD, BSD, and JSON schemas for data types.
Application services
- State machines — define, drive, and observe state transitions.
- Alarms and conditions — raise, acknowledge, and stream alarms. Alarm conditions use state machines, for example for shelving.
- Historical access — store and read value and event history.
- Aggregates — calculate processed history; read historical access first.
- File system client — transfer files through the standard file objects.
- Alias names — find nodes through named aliases.
- Node management — let clients add and delete nodes and references.
- Model change tracking — keep client caches current when the address space changes.
- NodeSet export — export a server's address space to NodeSet2 XML.
4. Use companion models
Companion specifications define models for particular industries and device types; Concepts explains how they relate to the base model. These libraries assume the server path and, for typed client access, the client path. The packages load the models that each model depends on.
- Device Integration (OPC 10000-100) — devices, topology, and locking.
- Asset Management Basics (OPC 10000-110; preview package) — make devices, machines, pumps or scales manageable assets: discovery, identification, health alarms, maintenance, documentation links and locations. Read Device Integration first.
- Software update (OPC 10000-100) — software package storage, installation, and confirmation. Read Device Integration first.
- ISA-95 (OPC 10030 and OPC 10031-4) — the common model and job control.
- Positioning (OPC 10000-210 and OPC 10000-211; preview package) — relative frames and geographic positions.
- Machinery (OPC 40001-1, -2, -3, -4 and -101; preview package) — machines with identification, server-driven state machines, process values, job management, energy and result transfer, based on the Industrial Automation, Device Integration, PA-DIM, ECM and ISA-95 models.
- Pumps (OPC 40223; preview package) — pumps and vacuum pumps, published both as Device Integration devices and as Machinery machines.
- Scales (OPC 40200 and OPC 30050; preview package) — weighing technology with every scale kind, scale systems, recipes and PackML state machines, based on the Machinery model.
- Robotics (OPC 40010-1; preview package) — motion-device systems, based on the Industrial Automation and Device Integration models. The guide's draft Robot Intent model is listed in stage 7.
- WoT connectivity (OPC 10100-1; preview package) — connect Web of Things assets. Its registry extension is listed in stage 7.
For more examples, including the Pumps and Machinery models, see the companion-model samples.
5. Prepare for production
Builds on the certificate trust you used in Getting started. Before you deploy a client or server, work through the production readiness checklist. It links to these guides for the details:
- Certificates — certificate stores, trust, and chain validation.
- Identity providers — authenticate users on clients and servers.
- Role-based user management — map identities to roles and permissions.
- Certificate manager — certificate lifecycle, rotation, and remote updates.
- Diagnostics — logging, metrics, tracing, auditing, and packet capture.
- Rate limiting — admission limits and busy signals during connection storms.
- Server resource isolation — per-caller limits and reserved capacity for startup and recovery.
- Profiles and facets — implemented profiles and platform boundaries.
- Container reference server — run the reference server in a container.
6. Advanced integration, reliability, and scale
Each group names the stages it assumes.
Transports and integration
Assumes the client or server path.
- Transports — UA-TCP, HTTPS, and WebSocket transports.
- REST binding — OpenAPI mapping, encoding negotiation, and HTTP authentication.
- OPC UA over OpenAPI — serve the OpenAPI document the stack generates from its REST routes and call the server from generated REST clients.
- Reverse Connect — server-initiated connections.
- Session-less invocation — let clients call Read, Browse, Call and the other §6.3 Services without a Session.
- PubSub external-server adapter — bind PubSub to an OPC UA server through a managed client session. Assumes the client and PubSub paths.
- PubSub transcoding — convert encodings, values, and metadata between PubSub messages.
- MCP server — let AI agents browse, read, write, and diagnose OPC UA servers.
- WoT / NodeSet conversion and WoT protocol bindings — convert Thing Descriptions and add protocol bindings. Read WoT connectivity first.
Session recovery and performance
The subscription guides assume the client path; the sizing guides assume Diagnostics.
- TransferSubscriptions — move server subscriptions to a new session.
- Durable subscriptions — keep subscriptions and queued notifications while clients are disconnected.
- Server scalability — sizing limits and bottlenecks.
- Benchmarks — measured performance and methodology.
Security infrastructure and fleet management
Assumes stage 5.
- ECC profiles — elliptic-curve security policies and their platform requirements.
- Crypto providers — replace the platform cryptography and keep private keys in hardware.
- Provisioning mode — configure a new server securely before exposing application data.
- Global Discovery Server — application registration and central certificate management.
- GDS sample — a runnable onboarding workflow.
- AuthorizationService — issue access tokens.
- KeyCredentialService — manage credentials for services that are not OPC UA. Its issued-token bridge is listed in stage 7.
High availability and deployment
Assumes a working single server and stage 5.
- High availability (preview package) — redundancy, failover, and distributed state.
- Replica-consistent NodeIds (preview package) — keep node identifiers identical across replicas; required before replicating an address space.
- Kubernetes (preview package) — cluster deployment, discovery, readiness, and secrets. Read high availability first.
- PubSub high availability (preview package) — redundant publishers and subscribers. Assumes the PubSub path.
Native AOT publishing
Publish an application as a native executable without a JIT compiler; start with Native AOT: publish an application. Feature-specific guidance:
- Servers with generated node managers
- Applications hosted with dependency injection
- PubSub applications
7. Draft and experimental capabilities
These guides implement working-group drafts or experimental extensions. Namespace URIs, NodeIds, and APIs can change before the specifications are published, so evaluate them before you depend on them in production. Each guide describes its current limitations.
- xRegistry (draft model; preview package) — the generic registry base model, resource storage, and federation.
- AI model management (draft model; preview package) — model catalogues, deployments, inference, and learning jobs. Builds on xRegistry.
- Vision (draft model; preview package) — perception, media, feedback, and client workflows.
- Robot Intent (draft model; preview package) — task-level motion commands. Does not require the Robotics model.
- OpenUSD (draft models; preview package) — bind values to OpenUSD scenes and materialize scenes in the address space.
- WoT Connectivity 1.1 registry (draft model; preview package) — registry and materialization. Read WoT connectivity first.
- KeyCredential issued-token bridge (experimental).
These samples combine several draft or preview capabilities. Read the guides for their models first:
- Bin picking cell — Robot Intent, Vision, and an OpenUSD scene.
- Visual inspection cell — Vision, AI model management, and ISA-95 job control.
- WoT aggregation sample — load Device Integration, Machinery, and Pumps models from WoT documents through the WoT Connectivity 1.1 registry, and bind them to two OPC UA source servers.
- Generator sample model (draft model) — generating-set simulation and scene composition.
Reference and upgrade
- What's New in 2.0 — a summary of new capabilities.
- Migration Guide — upgrade from 1.5.378, with topic-specific 2.0 guides and PubSub migration.
- Reference client — command-line configuration and transport profiles.
- Reference server — hosting and compliance-test setup.
- Reference PubSub client — publisher, subscriber, and external-adapter modes.
The Windows Forms reference applications are maintained in the Samples repository.
Contributing and maintaining the SDK
These documents describe building and maintaining this repository, not using the SDK in an application:
- Developer Guide — prerequisites, build, tests, and coding conventions.
- Continuous integration — pipelines and coverage gates.
- Native AOT test harness — build, run, and extend the Native AOT compatibility tests.
- Release process — release branches, versioning, backports, and recovery.
- Redundancy sample tests — process-level failover and soak validation.
- Fuzz testing — encoder, certificate, and network campaigns.