Revise ServiceControl Docs: Consistent Naming & Flow Accuracy (#7425)

* add clarity to queue forwarding

Author: soujay

monitoring/custom-checks/index.md

@@ -1,7 +1,7 @@
 ---
 title: Custom Checks
 summary: Enable endpoint health monitoring by running custom code using the Custom Checks plugin and ServiceControl
-reviewed: 2024-10-24
+reviewed: 2025-07-06
 isLearningPath: true
 redirects:
   - nservicebus/operations/custom-checks
@@ -14,12 +14,12 @@ The Custom Checks plugin enables endpoint health monitoring by running custom co
 graph LR
 
 subgraph Endpoint
-CustomChecks[Custom Checks]
+CustomChecks[Custom Checks Plugin]
 end
 
 CustomChecks -- Custom Check<br>Data --> SCQ[ServiceControl<br>Input Queue]
 
-SCQ --> SC[ServiceControl<br>instance]
+SCQ --> SC[ServiceControl Error<br>instance]
 
 SC -. Integration<br/>Events .-> Integration[Integration<br/>Event Handler]
 

monitoring/heartbeats/index.md

@@ -1,7 +1,7 @@
 ---
 title: Heartbeats
 summary: Use the Heartbeat plugin to monitor the health of the endpoints
-reviewed: 2024-10-31
+reviewed: 2025-07-06
 component: Heartbeats
 isLearningPath: true
 versions: 'Heartbeats:*'
@@ -20,12 +20,12 @@ The Heartbeat plugin enables endpoint health monitoring by sending regular heart
 graph LR
 
 subgraph Endpoint
-Heartbeats
+Heartbeats[Heartbeats Plugin]
 end
 
 Heartbeats -- Heartbeat<br>Data --> SCQ
 
-SCQ[ServiceControl<br>Input Queue] --> SC[ServiceControl]
+SCQ[ServiceControl<br>Input Queue] --> SC[ServiceControl Error Instance]
 
 SC -. Integration<br/>Events .-> Integration[Integration<br/>Event Handler]
 

monitoring/metrics/index.md

@@ -1,7 +1,7 @@
 ---
 title: Metrics
 summary: Collect metric data about endpoint performance using the Metrics plugin
-reviewed: 2024-10-30
+reviewed: 2025-07-06
 component: Metrics
 versions: 'Metrics:*'
 related:
@@ -28,12 +28,11 @@ end
 
 MetricsSC -- Metric Data --> MQ
 
-MQ[Metrics Queue] -- Metric Data --> Monitoring[ServiceControl<br>Monitoring<br>Instance]
+MQ[Monitoring Queue] -- Metric Data --> Monitoring[ServiceControl<br>Monitoring<br>Instance]
 
 Monitoring -- Endpoint<br>performance<br>data --> ServicePulse
 ```
 
-
 ## Set up metrics
 
 To enable collecting metrics in an environment:

servicecontrol/errorlog-auditlog-behavior.md

@@ -1,40 +1,39 @@
 ---
 title: ServiceControl Forwarding Log Queues
 summary: Details of the ServiceControl audit and error configuration and forwarding behavior
-reviewed: 2025-06-27
+reviewed: 2025-07-25
 ---
 
 ## Audit and error queues
 
-ServiceControl consumes messages from the audit and error queues and stores these messages locally in its own embedded database. These input queues names are specified at install time.
+ServiceControl Error and Audit instances consume messages from endpoint-defined `audit` and `error` queues. These are specified during instance setup and ingested through the instance's configured input queues, such as `Particular.ServiceControl` and `Particular.ServiceControl.Audit`. Once received, messages are persisted to ServiceControl's embedded RavenDB database. These input queues names are specified at install time.
 
-ServiceControl can also forward these messages to two log queues:
+Optionally, ServiceControl can forward these messages to external log queues:
 
- * Error messages are optionally forwarded to the _error_ log queue. Default: `error.log`.
- * Audit messages are optionally forwarded to the _audit_ log queue. Default: `audit.log`.
+* Error messages are optionally forwarded to the _error_ log queue. Default: `error.log`.
+* Audit messages are optionally forwarded to the _audit_ log queue. Default: `audit.log`.
 
-This forwarding behavior can be enabled or disabled through ServiceControl Management.
+This forwarding behavior is controlled via ServiceControl Management and can be enabled or disabled as needed.
 
 ![](managementutil-queueconfig.png 'width=500')
 
 ## Processing failures are not forwarded immediately
 
-Failed imports are not forwarded to the error log queue immediately. These will be stored in ServiceControl as Failed Imports or in the error queue of the ServiceControl instance type. Messages are forwarded by ServiceControl only after it is successfully stored in its datebase.
+When forwarding is enabled, ServiceControl does not forward [failed imports](/servicecontrol/import-failed-messages.md) to log queues immediately. It first attempts to ingest the messages from the error or audit queues to persist them in its embedded RavenDB database. Only after the message is successfully stored, does ServiceControl forward a copy of the messages to the configured log queues (error.log and/or audit.log). If the message ingestion fails (e.g., due to message corruption, transport issues , invalid headers etc.) then the message is not forwarded. Instead it is stored internally in the database under the `FailedAuditImports` and `FailedErrorImports` collections. It may also be routed to the ServiceControl's internal error queue (Particular.ServiceControl.Error).
 
-If messages must be forwarded immediately, even if ServiceControl cannot process the messages, the solution is to invert the processing order. Failed messages should be sent to a `process_errors` queue. A custom process will read from the `process_errors` queue, then forward the messages to the `error` queue that ServiceControl will process.
+If immediate forwarding is required, regardless of whether ServiceControl can ingest the message or not, the solution is to invert the processing order. The endpoints are configured to send failed messages to a `process_errors` queue. A custom processor will read from this `process_errors` queue and can then forward the messages to the `error` queue that ServiceControl will process.
 
 The same can be done for audit messages.
 
-Forwarding by ServiceControl:
+Forwarding by ServiceControl(default):
 
    "error" -> ServiceControl -> "error.log" -> Custom Processor
 
-Forwarding by Custom Processor:
+Forwarding by Custom Processor(inverted model):
 
    "error" -> Custom Processor -> "error.log" -> ServiceControl
 
-This gives the custom processor control over message handling before ServiceControl does for audit and error processing.
-
+This inverted model gives external processors pre-ingestion control over message behavior, including filtering, tagging, and early forwarding. It can be similarly applied to audit messages.
 
 ## Error and audit log queues
 

servicecontrol/how.md

@@ -1,7 +1,7 @@
 ---
 title: How does ServiceControl work?
 summary: An overview of how ServiceControl collects and processes messages and data from an NServiceBus system
-reviewed: 2025-02-14
+reviewed: 2025-07-06
 ---
 
 ServiceControl is a background process that will collect and store data and make it available via an HTTP API to ServicePulse and ServiceInsight.
@@ -23,21 +23,21 @@ graph LR
   end
 
   Audit -- Audit<br>data --> AuditQ(Audit queue)
-  AuditQ --> ServiceControlAudit[ServiceControl<br>audit instance]
-  ServiceControlAudit --> AuditLog(Audit.Log<br>queue)
+  AuditQ --> ServiceControlAudit[ServiceControl<br>Audit Instance]
+  ServiceControlAudit --> AuditLog(audit.log<br>queue)
   ServiceControlAudit -. Integration<br>events .-> Watchers
 
   Plugins -- Plugin data --> SCQ
   Plugins -- SagaAudit<br>data --> AuditQ(Audit queue)
-  SCQ(ServiceControl<br>queue) --> ServiceControlError
+  SCQ(ServiceControl<br> input queue<br>Particular.ServiceControl) --> ServiceControlError
 
   Error -- Error<br>data --> ErrorQ(Error queue)
-  ErrorQ --> ServiceControlError[ServiceControl<br>error instance]
-  ServiceControlError --> ErrorLog(Error.Log<br>queue)
+  ErrorQ --> ServiceControlError[ServiceControl<br>Error Instance]
+  ServiceControlError --> ErrorLog(error.log<br>queue)
   ServiceControlError -. Integration<br>events .-> Watchers[Subscribers]
 
-  Monitoring --> MonQ(Monitoring queue)
-  MonQ --> ServiceControlMonitoring[Monitoring instance]
+  Monitoring --> MonQ(Monitoring queue<br>Particular.Monitoring)
+  MonQ --> ServiceControlMonitoring[ServiceControl<br>Monitoring Instance]
 
   classDef Endpoints fill:#00A3C4,stroke:#00729C,color:#FFFFFF
   classDef ServiceControlInstance fill:#A84198,stroke:#92117E,color:#FFFFFF,stroke-width:4px