ServiceControl is the monitoring component of the Particular Service Platform: it ingests audit and error messages, tracks endpoint heartbeats, and exposes results over an HTTP API consumed by ServicePulse. For local run and debug steps, see the README.md. For test categories and setup, see testing.md. For rules a change must follow, see the Guidelines section.
src/— ServiceControl, ServiceControl.Audit, ServiceControl.Monitoring instances, persisters, and their test projectsdocs/— design rationale, testing guidance, guidelines, and architecture decision recordsdeploy/— PowerShell installation and management modules for ServiceControl instancestools/— build and CI helper scripts.github/workflows/— CI pipelines for build, test, container publishing, and dependency maintenance
- ServiceControl documentation — public documentation entry point
- README.md — how to run and debug ServiceControl, ServiceControl.Audit, and ServiceControl.Monitoring locally
- Testing overview — index of test kinds, local setup for each, the cloud database tests, and the scenario checklists to rerun after a change
- Deployment and Packaging — how instances are packaged and deployed
This section points to sources that explain why ServiceControl is designed the way it is. Each entry says which question it answers. How-to material such as testing setup stays in the pages linked under Start here.
- Ingestion pipeline — why batch parallelism is a storage decision, not an instance decision
- Error ingestion design — why the relational persisters write failed messages with hand-written SQL
- Message body storage — where the Audit SQL Server and PostgreSQL persisters keep message bodies, how retention removes them, and which settings are optional
- Bulk retries design — how ServiceControl retries failed messages in bulk
- Retries over Azure Storage Queues transport — how retries behave with one or several storage accounts
- Data versioning design — which invariant keeps a cached API response from going stale
- Event log design — what the event log is and what it records
- Multiple ServiceControl instances communication — how primary, audit, and monitoring instances talk to each other
- Handling unavailable runtime dependencies — how instances react when a dependency is unavailable
- Telemetry — how to configure telemetry export and which metrics instances emit
- Throughput collection — how usage data is collected and why the throughput queue has a fixed name
- SQL persister schemas — which schema each SQL persister uses by default and why a primary and an audit instance cannot share one
- Usage report contents: every key the usage report carries, every setting it leaves out, and why
- Database schema and index changes — any change to a RavenDB index definition, a document convention, or an EF Core entity or migration: treat it as a breaking change, ship it in a major release or opt-in in a minor, and record it in the upgrade guide in the same pull request.
- Prefer Microsoft abstractions — changes under
src/**exceptsrc/ServiceControl.Config/**that add or change a hosted service, host or builder extension, service registration, or logging: use the Microsoft abstraction, anIHostedServicefor background work, andILogger<T>. - Prefer explicit container registration — changes under
src/**exceptsrc/ServiceControl.Config/**that add or change a service registration or constructor dependency: register services explicitly and inject through constructors. - Prefer explicit persistence operations — changes under
src/*Persistence*/**and any change that adds or changes a persistence operation or unit of work: use a direct data-store method that commits before it returns, and a unit of work only for caller-composed atomic batches.
- NServiceBus: logging — when Core guarantees an
ILoggerFactoryinside an endpoint, and how components should log
- Architecture and design decisions
- RavenDB index search engine and rebuilds — which search engine a new or rebuilt index uses, why ServiceControl no longer writes database engine settings, how developers and operators learn about an index rebuild, why a locked index with a changed definition stops the start-up, and why ServiceControl queries only through static indexes
- RavenDB index database placement — which database an index class is deployed to in the error persister, why the namespace decides it, and how to add a new index
A pull request is listed here only when it is the canonical record for a decision area: it establishes a durable constraint or convention, or rejects an alternative likely to return, and no docs/ file or ADR covers it. Bug fixes and routine changes are not listed; recover them from git log and gh pr view.
- Pagination limits belong to the API layer, not the persister — #5899
- Timestamps in the error instance come from an injected
TimeProvider, notDateTime.UtcNow— #5843 - HTTPS certificates load during settings validation so an unusable certificate fails fast, and an ingestion-only worker serves its own certificate — #5891, #5923
- Endpoint throughput recording uses an atomic upsert because duplicate keys are routine, not exceptional — #5895
- Failed audit imports use deterministic ids derived from the message id so repeated failures do not duplicate — #5919
- SQL Server and PostgreSQL primaries can be upgraded, but the upgrade path does not create them — #5921
- New RavenDB databases use the Lucene search engine, and indexes still on Corax are flagged — #5833
Keep this index current when a canonical source is added, replaced, or retired; link, do not copy.