> For the complete documentation index, see [llms.txt](https://docs.pharos.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.pharos.ai/platform-overview/pharos-platform-architecture/logs/log-ingestion-methods/connected-orgs.md).

# Connected Orgs

Learn how to push logs between different Salesforce environments for centralized observability.

Connected Orgs enables cross-environment log aggregation by pushing logs from one Salesforce org to another. This capability transforms how teams manage observability across complex Salesforce landscapes—whether you need centralized visibility across multiple sandboxes, long-term archival to manage storage costs, or unified monitoring across regional production instances.

## Why Connected Orgs Matter

Modern Salesforce implementations rarely exist as a single production org in isolation. Most organizations operate dozens of environments—development sandboxes, QA environments, UAT instances, training orgs, hotfix sandboxes, and multiple production orgs for different business units or geographic regions. Managing observability across these environments creates significant operational challenges.

Without Connected Orgs, teams face fragmented visibility where they must log into each environment separately to review errors, making it impossible to identify systemic issues affecting multiple environments. Storage constraints become problematic as log volumes grow, forcing organizations to aggressively delete historical data that might be valuable for trend analysis or compliance. DevOps teams struggle to monitor lower-tier environments, often discovering errors only after they've been promoted to production. Finally, for enterprises operating multi-org architectures, there's no unified view of system health across the entire Salesforce estate.

Connected Orgs solves these challenges by creating a log flow infrastructure between Salesforce instances. Logs can be pushed from source orgs (where errors occur) to target orgs (where monitoring happens), enabling centralized visibility, archival strategies, and multi-org monitoring—all without complex middleware or external systems.

{% hint style="info" %}
**Native Architecture:** Connected Orgs operates entirely within Salesforce's platform using standard OAuth connections. No external infrastructure is required—logs flow directly from org to org through Pharos's own Salesforce API endpoint, under Salesforce's security model.
{% endhint %}

## Core Concepts

### Source and Target Orgs

In a Connected Orgs configuration, the **source org** is where errors occur and logs are generated, while the **target org** is where logs are sent for centralized monitoring or archival. A single source org can push logs to multiple targets, and a single target can receive logs from multiple sources, creating flexible network topologies.

### Broadcast and Passthrough

By default a connection **broadcasts**: the source org keeps its own copy of each log and sends a copy to the target. With **Passthrough Mode** turned on, the source keeps no copy. Logs go straight to the target as they are written, and are stored locally only if the target can't be reached.

### Filter Criteria

Each connection can restrict what it sends. Turning on filters and adding criteria means a log is transmitted only when those criteria evaluate true — by category, functional area, or any other field on the log record, combined however you need. Without filters, everything goes. The point is to transmit only logs that earn their keep in the target org, since every one consumes storage there as well as here.

### Bidirectional Sync vs. Unidirectional Push

Connected Orgs supports both unidirectional push (logs flow one direction only) and bidirectional sync (logs can flow in both directions). Most use cases employ unidirectional push—sandboxes push to production, or production pushes to archive. Bidirectional sync is rare but useful for specialized scenarios like disaster recovery configurations.

## Common Use Cases

### Centralized Sandbox Monitoring

Enterprise teams operating multiple sandboxes for different stages of their DevOps pipeline benefit from centralized visibility. In this configuration, development sandboxes, QA environments, UAT instances, and training orgs all push their logs to a central monitoring org (often production or a dedicated DevOps org).

This creates a single pane of glass where QA teams can monitor all test environments without switching contexts, developers can trace issues across environments as code promotes through the pipeline, and leadership can assess overall quality trends before production deployment. The central monitoring org becomes the authoritative source for cross-environment observability.

**Example Configuration:**

| Source Org   | Target Org         | Filter                                   |
| ------------ | ------------------ | ---------------------------------------- |
| Dev Sandbox  | Central Monitoring | Log Level equal ERROR                    |
| QA Sandbox   | Central Monitoring | No filter — send everything              |
| UAT Sandbox  | Central Monitoring | No filter — send everything              |
| Training Org | Central Monitoring | Narrowed to the categories worth keeping |

{% hint style="success" %}
**DevOps Integration:** Centralized sandbox monitoring transforms how teams approach release quality. Instead of discovering errors after production deployment, QA teams can proactively identify and resolve issues in UAT—dramatically reducing production incidents.
{% endhint %}

### Long-Term Archival

Production orgs often face data storage constraints as log volumes grow. Rather than aggressively deleting logs and losing historical data, organizations can implement archival strategies using Connected Orgs.

In this configuration, the production org retains recent logs (typically 30-90 days) for active troubleshooting, while older logs are pushed to a dedicated archive org with higher storage capacity or lower storage costs. The archive org serves as long-term historical storage for compliance, trend analysis, or rare deep-dive investigations.

**Example Configuration:**

| Phase        | Action                    | Retention   |
| ------------ | ------------------------- | ----------- |
| Active       | Logs in production org    | 0-30 days   |
| Archive      | Push to archive org       | 31-365 days |
| Deep Archive | Export to external system | 365+ days   |

This tiered approach balances accessibility (recent logs in production), cost efficiency (older logs in cheaper storage), and compliance requirements (long-term retention outside Salesforce, using standard data export tooling for the deepest tier).

### Multi-Org Architecture Monitoring

Enterprises operating Salesforce at scale often deploy multiple production orgs—regional instances for data residency compliance, business unit-specific orgs for different divisions, or brand-specific orgs for portfolio companies. Monitoring system health across these distributed architectures is challenging.

Connected Orgs enables unified visibility by having all production orgs push logs to a global monitoring org. This allows central platform teams to monitor health across all regions, identify systemic issues affecting multiple orgs, and benchmark performance between different instances.

**Example Configuration:**

```mermaid
graph LR
    NA[North America Prod] --> GM[Global Monitoring Org]
    EMEA[EMEA Prod] --> GM
    APAC[APAC Prod] --> GM
    LATAM[LATAM Prod] --> GM
    GM --> D[Unified dashboard - health across all regions]
```

The global monitoring org becomes the command center for enterprise-wide observability, with drill-down capabilities to investigate issues in specific regions.

### Compliance and Audit Trail

Regulated industries (healthcare, financial services, government) often require tamper-proof audit trails and long-term log retention. Connected Orgs supports compliance requirements by pushing logs to a dedicated compliance org with restricted access and extended retention.

In this configuration, all logs from production are immediately pushed to the compliance org, which has restricted write access (only Pharos can create records), extended retention (7+ years), and separate security controls (different admin team). This creates an immutable audit trail that satisfies regulatory requirements without cluttering production storage.

## How a Connection Works

A connection is described from **both ends**: each org holds a record that names the other. Nothing flows until both halves exist, which is deliberate — neither org can unilaterally push data into another.

* **The target allows the source in.** Its *Receive from this org* record is an allow-list: the target accepts broadcast logs only from orgs it has such a record for, and silently ignores anything else. Saving the record also creates an External Client App in the target, which is what the source signs in through.
* **The source signs in to the target.** Its *Send to this org* record holds the connection. An admin signs in to the target once and allows access; the source stores an OAuth token for the target and refreshes it every hour. A connection between two orgs always uses this External Client App path, because a session login only works within a single org.
* **Logs are sent in the background.** When a log on the source finishes processing, it is marked as needing broadcast. A background job sends it to the target's Pharos API, one log per request, and marks it complete. Filter criteria decide which logs qualify; a connection can carry everything or a narrow slice — only integration errors, only a given functional area, only records matching whatever condition you express.
* **The target stores its own copy.** Each received log is labelled with the name of the target's record for that source and marked as originating from a broadcast, so it's always clear where it came from.

The order of setup follows from this: the target's record must exist before the source can sign in.

{% hint style="info" %}
**No backfill:** only logs that finish processing after the connection is in place are sent. Logs already in the source org, and logs created while a connection was invalid, stay where they are.
{% endhint %}

For the setup itself — the form, authentication and filters — see [Connected Orgs](https://docs.pharos.ai/configuration-guide/connected-orgs.md), or follow the [Broadcast Logs to a Hub Org tutorial](https://docs.pharos.ai/configuration-guide/connected-orgs/connected-orgs-broadcast-tutorial.md) for a complete walkthrough with video.

## Architecture Considerations

### Data Transfer Overhead

Pushing logs between orgs consumes platform resources in both the source and target. The source runs a background job that makes one API call per log for each target it sends to. The target receives each request and creates or updates the log record.

For most organizations this overhead is negligible. Orgs generating extremely high log volumes should still monitor API consumption, and narrow their filter criteria if it becomes constrained.

### Latency and Timing

Connected Orgs operates asynchronously, but it is designed to be **near real-time** rather than batched — a log typically reaches the target org shortly after it is created. What variation exists comes from how quickly the log finishes processing in the source org and which connection mode is in play, not from a fixed sync window.

Because delivery is asynchronous, an alerting rule in the target org still fires slightly later than the same rule would in the source. Where every second counts, alert from the source org and use the target for aggregation, correlation across orgs, and historical analysis.

### Security and Privacy

When logs flow between orgs, they carry potentially sensitive information—user IDs, record IDs, error messages containing data values. Organizations must consider data residency requirements (can logs from EU production flow to US monitoring org?), privacy regulations (does log transfer constitute data processing under GDPR?), and access controls (who can view logs in the target org?).

Pharos provides data masking capabilities that work across Connected Orgs—sensitive data can be masked before transmission, ensuring the target org never receives plaintext sensitive information. This is particularly important when pushing from production (with real customer data) to non-production monitoring orgs.

### Cost Implications

Target orgs consuming logs from multiple sources will experience increased data storage consumption. A monitoring org receiving logs from 10 source orgs will accumulate 10x the log volume. Organizations must factor this into storage capacity planning and potentially purchase additional data storage for monitoring orgs.

However, this centralized storage is often more cost-effective than maintaining separate Pharos installations in each environment. Storage in a single monitoring org is cheaper than storage fragmented across many sandboxes.

## Best Practices

### Design for Purpose

Don't default to "push everything everywhere." Design your Connected Orgs topology with clear objectives:

* **For archival:** Push old logs from production to cheap storage
* **For DevOps:** Push all sandbox logs to central monitoring for QA visibility
* **For compliance:** Push all logs to restricted-access compliance org
* **For multi-org:** Push from all regional orgs to global monitoring

Each topology serves a different purpose and should have its filter criteria set accordingly.

### Start Conservative, Expand Gradually

Begin with narrow filter criteria and widen them as you validate the configuration and watch resource consumption. It's easier to loosen a conservative filter than to dial back an aggressive one after millions of logs have already crossed.

### Monitor Resource Consumption

Even though Connected Orgs has minimal overhead, organizations should monitor API call consumption and data storage growth in target orgs. Pharos provides dashboards showing Connected Orgs activity—review these regularly to ensure configuration remains optimal.

### Document Your Topology

In complex environments with multiple Connected Orgs relationships, document the topology clearly. Create a diagram showing which orgs send to which targets, what filter criteria are configured, and what the retention policies are in each org. This documentation is invaluable when troubleshooting or onboarding new team members.

### Leverage for Testing

Connected Orgs isn't just for production use—it's valuable for testing and validation. Push logs from your QA environment to a developer sandbox where you can safely test new Pharos features, alerting rules, or dashboard configurations without affecting production monitoring.

## Troubleshooting

For connection problems — logs not arriving, expired tokens, login restrictions — see [Connected Orgs troubleshooting](https://docs.pharos.ai/configuration-guide/connected-orgs.md#troubleshooting).

## Summary

Connected Orgs extends Pharos observability beyond individual Salesforce environments, enabling centralized monitoring, long-term archival, multi-org visibility, and compliance-friendly audit trails. By pushing logs between orgs using native Salesforce infrastructure, teams can implement sophisticated observability topologies without external middleware or complex integrations. Whether managing a complex DevOps pipeline across multiple sandboxes or operating a global multi-org architecture, Connected Orgs provides the foundation for enterprise-scale Salesforce observability.
