Operating Lerian SRC

Lerian SRC carries your institution’s consultations to BACEN. An instance that is not ready is an operational event.

Health and readiness

GET /health reports liveness. GET /readyz runs the checks below. It answers 503 when a check reports down or degraded, and while the service shuts down.

Check	What it probes
`postgres`	The PostgreSQL database.
`outbox_dispatcher`	The loop that publishes events from the outbox. It reports `skipped` while event publication is held, for example with no broker.
`src_mq`	The IBM MQ connection that carries consultations.
`custody`	The PKCS#11 or KMIP provider.
`trust_anchor`	BACEN’s certificate.
`license`	The Lerian license server.
`runtime_config`	The runtime configuration store.
`declaration`	The permission declaration to Access Manager. It reports `skipped` while `IDP_DECLARATION_ENABLED` is `false`.
`startup_self_probe`	The startup self-check of the service.

GET /version returns the build version of the service.

IBM MQ

Lerian SRC connects to your institution’s own IBM MQ queue manager. That queue manager reaches BACEN over the RSFN. Set SRC_MQ_HOST, SRC_MQ_PORT, SRC_MQ_CHANNEL, and SRC_MQ_QUEUE_MANAGER. Lerian SRC applies no default for the port and the channel, so ask your IBM MQ team for them. Lerian SRC derives the queue names from SRC_CNPJ_BASE8:

Send queue: QR.REQ.<CNPJ base>.00038166.03.
Receive queue: QL.RSP.00038166.<CNPJ base>.03.

Set SRC_MQ_SEND_QUEUE and SRC_MQ_RECEIVE_QUEUE only when your queue manager uses other names. While SRC_MQ_BACKOUT_THRESHOLD is above 0, a message that fails delivery that many times moves to the backout queue. The default threshold is 5. The backout queue is the receive queue name followed by .BACKOUT, unless you set SRC_MQ_BACKOUT_QUEUE. Lerian SRC opens the backout queue when it connects, so create it on the queue manager before you start the service. When no IBM MQ call completes for SRC_MQ_STALE_AFTER, 30 seconds by default, the src_mq check reports degraded. The Lerian SRC image runs on linux/amd64.

Credentials and keys

Lerian SRC signs each message it sends to BACEN with your institution’s private key. It uses BACEN’s certificate to protect each message for BACEN. Lerian SRC uses the private key through PKCS#11 or KMIP. When you configure both, it uses PKCS#11. Set SRC_LOCAL_CERT_FILE to your institution’s certificate for that key, and SRC_BACEN_CERT_FILE to BACEN’s certificate. After you replace BACEN’s certificate, restart Lerian SRC. GET /v1/src/credentials returns the status of the credential.

Personal data

Lists, search results, and events show the person’s document masked, in documentMasked. The evidence trail returns the full record, including the document. Lerian SRC records each read of the evidence trail in the same transaction as the read. If it cannot record the read, the read fails.

Operator cases

GET /v1/src/operator/cases lists the open cases, newest first. Send status=closed for the closed cases, or status=all for both. How Lerian SRC works explains the legs. Close a case with the operation of its leg:

Leg	Operation
`orphan_response`	`POST /v1/src/operator/orphan-responses/{caseId}/closure`
`invalid_outbound`	`POST /v1/src/operator/invalid-dispatches/{caseId}/closure`

A budget_exhausted case has closable set to false. A closure of a case that is not open returns 404 with code SRC-0301. Watch two numbers on GET /v1/src/dashboard/consultations:

openOperatorCases: the operator cases that are open now.
pendingBeyondExpected: the consultations that stay pending longer than src.pending.alert_threshold, 15 minutes by default.

Runtime configuration (Systemplane)

Lerian SRC serves its runtime configuration admin API at /v1/system. Authentication and permissions names the permission it needs. The admin API accepts 30 requests per minute from each client IP address. A change takes effect without a restart. The tables list the keys that tune consultations, retries, rate limits, and retention. See System plane. Namespace tenant_policy

Key	What it controls	Default	Range
`src.channel.active`	The channel that carries consultations to BACEN.	`messaging`	`messaging`
`src.consultation.protection_types`	The protection types that a consultation can carry. A request with another type returns `422`.	`account_opening,ownership_change`	`account_opening`, `ownership_change`
`src.pending.alert_threshold`	How long a consultation can stay `pending` before `pendingBeyondExpected` counts it.	`15m`	`1m` to `168h`

Namespace runtime_config

Key	What it controls	Default	Range
`src.dispatch.max_attempts`	Attempts for each consultation.	`8`	1 to 20
`src.dispatch.backoff_initial`	Wait before the first retry.	`1m`	`1s` to `1h`
`src.dispatch.backoff_ceiling`	Longest wait between two attempts.	`30m`	`1m` to `24h`
`src.log.level`	Log level.	`INFO`	`DEBUG`, `INFO`, `WARN`, `ERROR`
`src.rate_limit.ip_max`	Requests that one client IP address can send in each window, in each replica.	`6000`	1 to 1000000
`src.rate_limit.ip_window`	Length of the rate-limit window.	`1m`	`1s` to `1h`
`src.retention.transient_purge_age`	Age after which the sweep can delete an idempotency key.	`24h`	`1h` to `720h`
`src.retention.transient_purge_batch`	Idempotency keys that one purge statement deletes.	`1000`	100 to 10000
`src.retention.resolved_orphan_payload_purge_age`	How long a closed orphan-response case keeps the message that Lerian SRC received.	`8760h`	`24h` to `8760h`

Storage, outbox and retention

Lerian SRC stores its state in PostgreSQL. Events leave through an outbox table, in the same transaction as the change they report. With no broker, the events stay pending in the outbox. The retention sweep deletes idempotency keys older than src.retention.transient_purge_age, 24 hours by default. Lerian SRC does not apply its own database schema. The br-src-migrations image applies it. Run that image before you start the br-src image.

Metrics and tracing

Set ENABLE_TELEMETRY=true to export traces and metrics over OTLP to OTEL_EXPORTER_OTLP_ENDPOINT. Lerian SRC has no /metrics endpoint. See Observability for the platform view.

Deployment posture

DEPLOYMENT_MODE takes local, byoc, or saas. One deployment serves one institution. Environment variables defines a production deployment and marks each setting that it requires. A missing required setting stops the boot.

​Health and readiness

​IBM MQ

​Credentials and keys

​Personal data

​Operator cases

​Runtime configuration (Systemplane)

​Storage, outbox and retention

​Metrics and tracing

​Deployment posture