Distribution Service and Receiver Service Paths How path ownership, network direction, landing trails, and restart boundaries actually work in a modern GoldenGate transport layer.
The focus is not generic Microservices administration. It is the practical transport boundary an operator must understand when building source-initiated push paths, target-initiated pull paths, fan-out routes, or tightly controlled cross-zone delivery.
Distribution Service routes committed changes between deployments. Receiver Service lands them as a target trail. Neither service replaces capture, checkpoints, or apply.
The core design choice is path ownership: let the source push toward the target, or let the target pull from the source when network policy makes inbound access unacceptable.
Healthy transport means more than a green icon. You need path state, path statistics, advancing landing trails, and a Replicat checkpoint that confirms the handoff really completed.
Topic boundary: what this article covers and what it deliberately leaves out
Distribution Service and Receiver Service are the transport control surface in GoldenGate Microservices Architecture. They matter because the network hop is where ownership, security, restart behavior, and observability stop being implicit. The path object makes those decisions explicit.
This article covers the layer between an Extract-written trail on the source side and a landing trail on the target side. It explains how Distribution Service exposes or pushes trail data, how Receiver Service accepts or initiates that movement, how source-initiated and target-initiated paths differ, what to configure before creating the path, what to verify after creation, and where incidents usually hide.
Capture mode tuning, supplemental logging, integrated Extract registration, Replicat mapping, conflict detection, and database-specific apply design are not expanded here unless they directly change path behavior. The article stays on one GoldenGate topic only: service-managed trail transport between deployments.
What Distribution Service owns
Routing, path objects, exposure of trail sources, fan-out style delivery, and path-level observability such as message and byte statistics.
What Receiver Service owns
Inbound landing on the target side and, in target-initiated designs, the receive path that pulls from the source-side Distribution Service.
What still belongs elsewhere
Extract owns capture and local trail creation. Replicat owns checkpointed apply. A healthy path does not prove either side of that handoff is healthy.
How Distribution Service and Receiver Service fit into the Microservices architecture
GoldenGate Microservices keeps the queueing model intact. Extract writes to trail files, trail data moves over an explicitly managed path, and Replicat reads a landing trail at the far side. The services modernize control and observability; they do not eliminate the durable trail boundary.
Distribution Service is the routing service. Oracle describes it as the component that supports path-based distribution and the communication between a trail source and a trail target. Receiver Service is the inbound side. It receives incoming trail data for source-initiated delivery, and it can also create a receive path that pulls from the source Distribution Service when the target must own the network initiation.
The practical mistake is to treat these services as a cosmetic replacement for a classic data pump. In Microservices Architecture, the path object becomes the operational unit. It determines where the transport definition lives, which deployment's administrators can restart it, which credentials or trust material are relevant, and where you should begin diagnosis when trail movement stops.
Always reason from queue boundary to queue boundary. Ask four questions: which trail is the source, which service owns the path, where the landing trail is written, and which process is expected to resume first after a failure. Most transport incidents become much easier once those four boundaries are explicit.
Choose the path owner before you choose the syntax
The important decision is not which screen to click. It is whether the source side should own a push path or the target side should own a pull path. That design choice changes network direction, restart ownership, change-management scope, and how each operations team interprets a failure.
| Pattern | Use it when | Where the object lives | Operational consequence |
|---|---|---|---|
| Source-initiated Distribution Path | The source deployment is allowed to open outbound connectivity toward the target and central transport ownership on the source side is acceptable. | Distribution Service on the source deployment owns the DISTPATH object. |
The source team usually controls start, stop, and restart behavior. Fan-out from one source to several targets is straightforward. |
| Target-initiated Receive Path | The target environment is in a protected zone and policy says the target may initiate outbound connections but should not accept source-opened sessions. | Receiver Service on the target deployment owns the RECVPATH object. |
The target team owns restart behavior. A read-only representation appears on the source side, but it is not the primary control object. |
Why source-initiated remains common
It is simple to visualize: Extract writes a local trail, Distribution Service pushes it toward a target endpoint, Receiver Service lands the trail, and Replicat reads it. For straightforward point-to-point routing or fan-out, that ownership model is usually the least surprising.
Why target-initiated matters
It solves a real security-zone problem. The target can pull from the source Distribution Service, keep local ownership of the receive object, and avoid treating the source network as a place that opens connections inward on demand.
Path ownership also changes troubleshooting boundaries. If the target owns the receive path, a stopped or misconfigured path is not primarily a source-side incident even when the local trail is advancing normally on the source.
Prerequisites and security assumptions that should exist before path creation
Path creation is one of the easiest places to waste time because the visible syntax looks small while the real prerequisites are distributed across two deployments. Most failed path builds are not caused by the last command. They are caused by skipped groundwork.
A path cannot move a trail that does not exist or that is not advancing. Validate the source trail name, location, and group ownership before working on transport.
Remote path creation depends on live services in both the appropriate deployments, not just on deployment metadata.
Choose a source local-trail prefix and a target landing-trail prefix deliberately. A landing trail is an operational handoff, not a throwaway filename.
Oracle requires path connections for remote paths, except where a hub-style environment removes the need for remote service-to-service connection management.
For target-initiated paths, the source side still authorizes the connecting Receiver Service. If the source does not recognize that remote identity, the pull model fails before trail movement begins.
A path that successfully lands a trail without a prepared Replicat group still creates backlog, disk growth, and confusion about whether transport is truly done.
In a target-initiated model, the source deployment still participates in security by defining the remote path connection that authorizes the target Receiver Service. The target owns the receive path object, but the source remains the gatekeeper for who is allowed to connect to its Distribution Service.
| Preparation item | Why it matters | What good looks like |
|---|---|---|
| Local trail plan | The path reads from a trail source, not directly from redo. | You know exactly which Extract and trail prefix the path will expose or push. |
| Landing trail plan | Receiver Service writes the durable queue that Replicat will use. | The target trail name, storage location, and consumer are defined. |
| Connection and trust | Remote service connectivity requires authorization/trust material. | The remote deployment identity is recognized before the actual path build. |
| Ownership agreement | Push and pull models are runbook decisions. | The team restarting the object during an incident owns the path definition. |
Build a source-initiated path when the source should push toward the target
A source-initiated path is the cleanest model when the source is allowed to open the transport session. The source Distribution Service owns the path object, points at a target endpoint, and sends trail data that the target Receiver Service lands in a target trail.
Confirm the routing boundary before creating the path
Decide the exact source Extract and trail source, the target deployment that will receive the data, the target trail prefix that should be created or appended, and the ports associated with the Receiver Service endpoint and the target deployment's Service Manager.
Source-side inputs
exacct as the Extract group, lt as the local trail being exposed, and dp_acct_core as the outbound path name.
Target-side inputs
rt as the landing trail prefix, a reachable Receiver Service endpoint, and a Service Manager port that matches the target deployment.
Create the distribution path on the source deployment
Run the following while connected to the source deployment in Admin Client. This is a current, documented command pattern for adding a distribution path that targets a Microservices trail endpoint.
ADD DISTPATH dp_acct_core, EXTRACT exacct, TARGET wss://core-ogg-02:13000/services/v2/targets?trail=rt, FORWARDONLY, NOCOMPRESS, MGRPORT 9001 START DISTPATH dp_acct_core
The target URI names the target-side trail endpoint and the landing trail prefix. MGRPORT identifies the target deployment's Service Manager port. The path definition can exist before it runs, so the START DISTPATH step is operationally important; creation alone does not move data.
Verify the path itself before checking Replicat
Do not jump straight to the target database. First confirm that the transport object is up and carrying data at the service layer.
INFO DISTPATH dp_acct_core STATS DISTPATH dp_acct_core HEALTH DEPLOYMENT west_hub
INFO DISTPATH tells you whether the path exists and is running. STATS DISTPATH is where transport becomes observable: Oracle exposes path statistics such as logical change record counts and network-level metrics. If those counters do not move while the source Extract is active, the incident is still inside the transport boundary.
Confirm the landing trail and only then hand off to Replicat analysis
A source-initiated path is successful when the target landing trail advances and Replicat can consume it. If the landing trail grows but Replicat lags, the transport hop is not the bottleneck. Stop attributing the incident to Distribution Service once the trail handoff is complete.
It proves that the source deployment can expose the correct trail, that the target endpoint is reachable and authorized, and that Receiver Service can land the remote trail. It does not, by itself, prove mapping correctness, target DDL readiness, or apply throughput.
Build a target-initiated path when the target should pull from the source
Target-initiated delivery exists for environments where the target deployment must control the connection. Receiver Service on the target creates the receive path, connects to the source Distribution Service, and lands the trail locally. While that path runs, GoldenGate exposes a corresponding read-only distribution-path object on the source side.
Authorize the relationship on the source before creating the receive path
This is the part operators often miss. A target-initiated path is not purely a target-side feature. The source deployment must already recognize the remote target deployment through a path connection definition so that only authorized Receiver Services can connect and pull from the source Distribution Service.
Target-initiated does not mean source-agnostic. It means the target owns the receive object and starts the network session. The source still controls whether that target is trusted to consume the source trail.
Create the receive path on the target deployment
Run the following while connected to the target deployment in Admin Client. The FROM clause names the source Distribution Service trail endpoint, and TARGETTRAIL defines the landing trail written locally on the target.
ADD RECVPATH recv_acct_pull FROM ogg://edge-ogg-01:9003/services/v2/sources?trail=lt TARGETTRAIL ./dirdat/rt, BEGIN NOW INFO RECVPATH recv_acct_pull STATS RECVPATH recv_acct_pull
BEGIN NOW starts the receive path immediately instead of leaving it created but idle. The source URI points at the trail source exposed by the source Distribution Service. The target does not read the local trail directly from the source file system; it reads through the Distribution Service endpoint.
Interpret what appears on each side after startup
Once the receive path starts, the target deployment owns the main runtime object. The source deployment will show a corresponding distribution-path representation, but Oracle treats that source-side object as read-only in this model. That detail matters during incidents because the restart authority and the runbook stay with the target deployment.
Creates and starts
RECVPATH.Exposes source trail through Distribution.
Target lands a normal trail for Replicat.
Start with target path definition and target-side trust.
Return to Extract and source trail generation.
Move downstream to Replicat, not back to the path.
Know when target-initiated is the better operational contract
Use it when the target team must own recovery, when network segmentation requires the target to initiate outward, or when the source estate should expose a service endpoint but should not keep writable transport definitions for every protected target. It is not intrinsically more modern than source-initiated; it is simply the better fit when control must sit near the landing side.
Verify and diagnose the path layer in the right order
The transport layer is easiest to debug when you do not mix boundaries. Check deployment health, then the path object, then path statistics, then landing-trail behavior, and only then the apply boundary. Skipping directly to database row counts hides whether the transport layer is actually healthy.
| Checkpoint | Command or observation | Expected signal | What it means |
|---|---|---|---|
| Deployment service state | HEALTH DEPLOYMENT <name> |
Distribution & Receiver Service appear as running. | The path has a live control surface. If a required service is down, fix that before touching path syntax. |
| Path existence/lifecycle | INFO DISTPATH or RECVPATH |
The path exists and is not merely defined but disabled. | Creation succeeded and runtime state is inspectable. Disabled means created but not started, or stopped after an error. |
| Transport activity | STATS DISTPATH or RECVPATH |
LCR and network counters move when source activity exists. | The service layer is doing real work rather than only presenting a valid definition. |
| Landing trail progression | Observe trail files and Replicat point | The landing trail is created and advances with incoming change. | Receiver Service completed the remote handoff and Replicat now has something durable to consume. |
| Apply boundary | Replicat status and checkpoint position | Checkpoint advances behind the landing trail. | The transport layer has handed off cleanly. Remaining lag is downstream. |
HEALTH DEPLOYMENT west_hub HEALTH DEPLOYMENT east_core INFO DISTPATH dp_acct_core STATS DISTPATH dp_acct_core INFO RECVPATH recv_acct_pull STATS RECVPATH recv_acct_pull
The exact path names differ by pattern, but the method stays stable: ask whether the deployment is healthy, whether the path object is live, whether the service counters move, and whether the landing trail advances. That sequence prevents the common mistake of blaming a target apply issue on a transport service that is already doing its job.
In practice material, GoldenGate exposes detailed path statistics including logical change record counts and network metrics. That is the right level to inspect when you need proof that the service is moving change, not just maintaining a valid configuration entry.
Operational consequences that good designs make explicit
Path configuration is not a one-time build artifact. It sets the incident boundary. If the design makes ownership, restart location, and landing-trail purpose unclear, the first outage will expose that ambiguity immediately.
Backlog accumulates somewhere specific
If Distribution Service cannot deliver, the source trail queues work. If Receiver Service lands the trail but Replicat is down, backlog accumulates in the target trail. Those are different incidents and shouldn't share a runbook.
Restart authority matches ownership
Source-initiated paths belong in source-side operational ownership. Target-initiated paths belong in target-side operational ownership. Anything else creates change-management delay during a real interruption.
Trail names are governance
A landing trail should map cleanly to one feed and one consumer boundary whenever possible. Clear trail naming shortens diagnosis and makes it obvious which downstream Replicat depends on a path.
Where each pattern tends to shine
| Design pressure | Usually favors | Why |
|---|---|---|
| Simple point-to-point delivery | Source-initiated path | It keeps the transport object next to the source trail and is easy to reason about for 1:1 topologies. |
| Fan-out to multiple targets | Source-initiated paths | One source deployment can maintain several outbound paths, each with its own landing target and consumer. |
| Protected target network | Target-initiated path | The target can initiate the session and keep restart control local while the source exposes only the authorized trail. |
| Separate operations teams | Whichever side owns recovery | Choose the pattern that matches your incident model. Wrong ownership choices cause paging/responsibility confusion. |
If the same team owns the source Extract, source trail retention, and outbound routing, source-initiated paths are usually the cleanest option. If the target platform team must own recovery and connectivity into the protected zone is asymmetric, target-initiated paths create the healthier operating contract.
Failure patterns: symptom first, then the boundary to inspect
Transport incidents are much faster to solve when you start from the symptom and map it to the nearest boundary instead of rereading every parameter file. Distribution Service and Receiver Service failures usually cluster around authorization, endpoint mismatch, disabled objects, or incorrect assumptions about where data should be landing.
| Symptom | Likely boundary | What to inspect first | Next action |
|---|---|---|---|
| Path exists but moves no change | Transport object or source trail selection | Whether path is started, source trail advances, and path points at intended trail endpoint. | Fix lifecycle state or endpoint binding before touching Replicat. |
| Target-initiated pull never starts | Source authorization or target receive-path definition | Source path connection/trust config plus the exact FROM endpoint in ADD RECVPATH. |
Correct trust relationship or endpoint path, then restart the receive path. |
| Path statistics healthy but target lag persists | Landing-trail consumption, not transport | Replicat state, checkpoint position, and target database behavior. | Stop blaming Distribution Service. Move the incident boundary to apply. |
| Source trail grows while path remains down | Outbound connectivity, service availability, or path failure | Distribution Service health, path state, and recent path statistics. | Restore transport promptly or plan for disk growth on the source side. |
| Landing trail never appears on target | Receiver endpoint or target trail definition | Target endpoint trail name, receive path TARGETTRAIL, and whether Receiver is running. |
Correct endpoint/trail definition, restart path, and watch trail creation immediately. |
A green deployment status is not the same as a working path. The services may be up while the specific path is disabled, pointed at the wrong trail, or blocked by missing authorization. Always inspect the object that actually owns the transport session.
Version-aware notes that keep older knowledge useful without treating it as the baseline
The underlying path concepts are stable, but some surrounding language has shifted over time. Older 12.3-era course and lab material often says Distribution Server and Receiver Server. Current GoldenGate documentation uses Distribution Service and Receiver Service as the standard names in Microservices Architecture.
The commands remain recognizable across that naming shift: DISTPATH still refers to the managed distribution-path object and RECVPATH to the managed receive-path object. What matters more in modern practice is that current documentation emphasizes explicit path connections, service endpoints, and the target-initiated model where Receiver Service owns the pull path and surfaces a read-only source-side path representation while it runs. In OCI-managed GoldenGate connections, WSS is the expected transport choice, so protocol selection is not always arbitrary across platforms.
What stayed stable
Trail-based decoupling, service-managed path objects, path statistics, and the need to keep transport diagnosis separate from apply diagnosis.
What changed in practice
The service vocabulary is now the default, remote path authorization is more explicit, and target-initiated pull is a first-class design choice rather than a niche workaround.
Keep the durable-queue mental model from classic GoldenGate, but do not keep the assumption that transport is an invisible side effect of a process group. In Microservices Architecture, path objects, service endpoints, and path ownership are part of the architecture, not just part of the tooling.
The focus is not generic Microservices administration. It is the practical transport boundary an operator must understand when building source-initiated push paths, target-initiated pull paths, fan-out routes, or tightly controlled cross-zone delivery.
Test your understanding
Select an answer and click Check.
Q1 — In a source-push configuration, which service initiates the trail transfer?
Q2 — Which protocol does GoldenGate Microservices use for secure trail distribution?
Q3 — A Distribution path is configured with a target path name. Where is this path defined?
Q4 — What happens to a Distribution path when the target Receiver Service is temporarily unavailable?
No comments:
Post a Comment