Skip to content

Latest commit

 

History

History
67 lines (49 loc) · 7.11 KB

README.md

File metadata and controls

67 lines (49 loc) · 7.11 KB

Engineering context

About this repository

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 projects
  • docs/ — design rationale, testing guidance, guidelines, and architecture decision records
  • deploy/ — PowerShell installation and management modules for ServiceControl instances
  • tools/ — build and CI helper scripts
  • .github/workflows/ — CI pipelines for build, test, container publishing, and dependency maintenance

Start here

  • 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

Architecture and design

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.

Guidelines

  • 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/** except src/ServiceControl.Config/** that add or change a hosted service, host or builder extension, service registration, or logging: use the Microsoft abstraction, an IHostedService for background work, and ILogger<T>.
  • Prefer explicit container registration — changes under src/** except src/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.

Upstream contracts

  • NServiceBus: logging — when Core guarantees an ILoggerFactory inside an endpoint, and how components should log

Decisions and rationale

  • 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

Decisions recorded in pull requests

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, not DateTime.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.