Installation guide
For the AWS administrator and the Salesforce administrator who install WatchDog in their own AWS account. It runs entirely in your account, as containers on Amazon ECS (AWS Fargate), and your Salesforce data stays in your account.
1 · Before you start
What you buy
An AWS Marketplace subscription. You buy a number of Operations, Security or Complete units, one per Salesforce org, and assign one to each org in WatchDog Setup → Plan. Launching the subscription pre-fills the image and the Marketplace settings.
Requirements
- An AWS account with no other WatchDog installation. WatchDog's S3 bucket names are account-wide, so an account holds one installation. (Another region of the same account doesn't help.)
- Administrator access in that account for the installation. It creates IAM roles, a VPC and a CloudFormation stack.
- A Salesforce administrator for each org you connect, who can install a managed package and create an External Client App.
- About 30 minutes, most of it waiting for AWS to create the stack.
2 · Part 1 — AWS side
Step 1 · Launch the stack
Open your subscription in AWS Marketplace, choose Launch, then pick the CloudFormation delivery option and your region.
Step 2 · Fill in the parameters
| Parameter | What to enter |
|---|---|
ImageUri | Pre-filled. The WatchDog image for this version. |
LicenceToken | Leave blank. |
EntitlementSource, MarketplaceProductId | Pre-filled (license-manager and your product). Leave as they are. |
EntitlementMode | enforce applies your packages. Don't use off. |
AlarmEmail | Where operational and cost alarms go. Recommended. You'll need to confirm the subscription email AWS sends. |
ServiceTaskCount | 1 per service to start; 2 for high availability (the services then run in two Availability Zones); 0 pauses WatchDog. |
MaxTaskCount | The most tasks any service may scale out to during a burst. Default 20; it's your cost ceiling. |
ApiAllowanceSlowBelowPercent, ApiAllowancePauseBelowPercent | When an org's remaining daily Salesforce API allowance drops below these (defaults 30% and 15%), WatchDog fetches its logs one at a time, then pauses until the allowance recovers. This protects the allowance your own integrations share. |
CreateCloudTrail | true creates a CloudTrail trail for this account; set false if you already have an organisation or account trail. |
SalesforcePrivateKey, SalesforceClientId | Leave blank (recommended). Each org's key and External Client App are registered separately in Part 3. |
OpenAIKey, IpInfoToken, CloudFrontWebAclArn | Optional. AI keys are normally set per org in WatchDog Setup; an ipinfo.io token raises the rate limit for sign-in geolocation; a CloudFront WAF ACL (us-east-1) protects the web apps. Keys you enter here are stored in AWS Secrets Manager. |
EnablePrivateCanvasApi and the PrivateApi… fields | Leave false unless you need the private API (section 8). |
Acknowledge that the stack creates IAM resources, then Create stack. It takes about 15–20 minutes; the API Gateway VPC link is the slowest part.
Step 3 · Note the outputs
When the stack reaches CREATE_COMPLETE, find its outputs:
- In the AWS console, check the region in the top-right corner is the one you installed in.
- Go to CloudFormation → Stacks and choose your WatchDog stack: the one with the name you gave it, not the ones marked NESTED.
- Open the Outputs tab. Each output's value is in the Value column; the links can be clicked.
| Output | Used for |
|---|---|
ApiGatewayUrl | The Canvas App URL in Salesforce (Part 2), with a trailing /. |
RegisterSalesforceOrgConsoleUrl | Registering each Salesforce org (Part 3). |
CloudFrontUrl | Where the WatchDog apps are served from; Salesforce loads them for you. |
Step 4 · Create a key pair for the Salesforce connection
WatchDog signs in to Salesforce with the OAuth JWT flow. Create a 2048-bit (or larger) RSA key pair on your computer:
openssl genrsa -out watchdog_private.key 2048
openssl req -new -x509 -key watchdog_private.key -out watchdog_public.crt -days 730 -subj "/CN=WatchDog"
Keys smaller than 2048 bits are refused.
3 · Part 2 — Salesforce side
Step 5 · Install the managed package
Install the WatchDog managed package (version 0.4.0.1) in each Salesforce org you'll connect, from the link for that kind of org, signed in as an administrator:
| Org | Installation link |
|---|---|
| Production or Developer Edition | https://login.salesforce.com/packaging/installPackage.apexp?p0=04tJ20000011PCJIA2 |
| Sandbox | https://test.salesforce.com/packaging/installPackage.apexp?p0=04tJ20000011PCJIA2 |
Choose Install for Specific Profiles or Install for Admins Only, and include the integration user's profile.
Assign the WatchDog permission sets
| Permission set | Gives | Assign to |
|---|---|---|
| WatchDog User | The WatchDog app and the Pulse, Log Explorer, Process Lens, Security Monitoring and Know Your Org tabs | Everyone who uses WatchDog |
| WatchDog Setup Admin | WatchDog Setup: polling, alerts, integrations, AI, retention and Plan | The people who configure WatchDog |
| WatchDog Monitor Hub Admin | Monitor Hub: choosing who is monitored, sessions and Hypercare | The people who run monitoring |
System Administrators get Setup and Monitor Hub only when these admin permission sets are assigned. WatchDog checks the permissions itself, so a user without them can't change settings or start monitoring from any WatchDog tab.
Step 6 · Create the External Client App
Salesforce now creates apps like this in External Client App Manager (it replaced connected apps in App Manager). In Setup, open External Client App Manager and choose New External Client App:
| Setting | Value |
|---|---|
| Name / API Name | WatchDog Auth / WatchDog_Auth (must be exactly this) |
| Distribution State | Local |
| Enable OAuth | Yes. Callback URL https://login.salesforce.com/services/oauth2/callback; OAuth scopes Full access (full) and Perform requests at any time (refresh_token, offline_access) |
| Enable JWT Bearer Flow | Yes. Upload watchdog_public.crt as the certificate |
| Canvas | Enabled. Canvas App URL: your ApiGatewayUrl with a trailing /. Access method: Signed Request (POST). Location: Lightning Component. |
Create the app, then open its Policies tab and choose Edit. Under OAuth Policies set Permitted Users to Admin approved users are pre-authorized and IP Relaxation to Relax IP restrictions (WatchDog signs in from AWS addresses), and select the integration user's profile and the WatchDog User permission set, so everyone who uses WatchDog can open its tabs. Save.
You'll need the app's Consumer Key and Consumer Secret in Step 8: on the Settings tab, open OAuth Settings and choose Consumer Key and Secret.
Step 7 · Create the integration user
A dedicated service account with a full Salesforce licence and: View All Data, Manage Users, View Setup and Configuration, API Enabled, and View Event Log Files (for Data Exfiltration and Security Posture). Give it a permanent password.
A Salesforce Integration licence user isn't enough for the Operations modules: Salesforce doesn't let that licence read Apex debug logs or create trace flags and debug levels. It works for the Security modules only.
4 · Part 3 — Connecting the two
Step 8 · Register the org
In the AWS console, go to CloudFormation → Stacks → your WatchDog stack → Outputs, and click the link in the Value column next to RegisterSalesforceOrgConsoleUrl. It opens an AWS Systems Manager Automation form with the role pre-filled:
| Field | Value |
|---|---|
orgId | The org's 18-character ID (Setup → Company Information). |
consumerKey | The External Client App's Consumer Key. |
consumerSecret | The External Client App's Consumer Secret. |
privateKeyPem | watchdog_private.key as one line of base64: base64 -i watchdog_private.key | tr -d '\n' |
Click Execute. This starts a short-lived task that writes the credentials into your account's encrypted tables and parameters; it finishes in one to two minutes. The values pass through a temporary Secrets Manager secret that is deleted at the end, so they don't appear in task settings or CloudTrail. Run the form once per Salesforce org, and again to rotate a credential.
5 · Post-installation configuration
- Marketplace Assign a package to each org. WatchDog Setup → Plan → choose Operations, Security or Complete. One unit of that package is reserved for the org straight away. If you've used all your units, Setup says so; buy more on AWS Marketplace or move another org to a different package. Until an org has a package, its WatchDog apps show "not in your plan". Setup itself always opens.
- Set polling frequencies in Setup → Jobs & Polling, then Save Changes. A module whose frequency isn't saved doesn't run.
- Choose who is monitored in Monitor Hub. Debug logs are collected only for users with an active Monitor Hub session. By default, logs from users without a session are deleted without being stored (Setup → Jobs & Polling → orphaned logs).
- Set retention and alert thresholds in Setup, as you need.
- Optional: turn on sign-in locations in Setup → Alerts → Login Intelligence (Look up sign-in locations with ipinfo.io, off by default). It's needed for the sign-in map, Allowed Countries alerts and Data Exfiltration's geo-fence, and sends each new sign-in IP address to ipinfo.io.
- Confirm the alarm email: click the link in AWS's "Subscription Confirmation" email, or no alarm reaches you.
6 · Verifying it works
- WatchDog Setup opens in Salesforce.
- Marketplace Setup → Plan shows your package as Active.
- A monitored user appears in Monitor Hub with a live session.
- As that user, cause a harmless error in Salesforce, for example in the Developer Console's anonymous Apex:
String s = null; Integer n = s.length();. Within one polling interval it appears in Log Explorer, and opens as an execution tree. - There's no red licence banner at the top of the apps.
7 · Running costs, scaling and pausing
AWS charges your account directly. Approximate list prices in Sydney (ap-southeast-2), before tax:
| Configuration | Approx. per month |
|---|---|
| Always-on network and security (NAT gateway, load balancer, WAF, keys, monitoring) — also when paused | $88 |
| Running, 1 task per service | $210 |
| Running, 2 tasks per service (high availability) | $330 |
| A burst: the log parser at 20 tasks for one hour | $1 |
Data storage and request charges (DynamoDB, S3, API Gateway) come on top and grow with your log volume. Services add tasks when their queues back up, up to MaxTaskCount, and return to ServiceTaskCount when quiet. To pause WatchDog, update the stack with ServiceTaskCount = 0. Collection stops, the always-on costs remain, and nothing is lost.
8 · Optional private Canvas API
For organisations that require the Salesforce-to-AWS connection to stay on a private network: EnablePrivateCanvasApi = true adds a second, VPC-only API in a VPC you choose (one already connected to your network by VPN or Direct Connect). It adds the PrivateApiGatewayUrl output, which you use as the Canvas App URL instead. The public API remains available.
- It switches on private DNS for API Gateway in that VPC. Afterwards, every API Gateway address used from that VPC resolves to the private endpoint, so calls from that VPC to other public API Gateway APIs fail with 403. Choose a VPC where that doesn't matter.
- In Google Chrome, users can only reach a private address from a Salesforce page if your IT department sets the
LocalNetworkAccessAllowedForUrlspolicy through device management (Intune, Jamf or Group Policy). Safari needs no change.
9 · Upgrading
Update the stack with the new version's template or ImageUri. The services are replaced with no downtime, and the web apps are republished automatically when the new version starts. Parameters you don't change keep their current values.
10 · What leaves your account
WatchDog stores everything in your account. It makes these outbound calls:
- Salesforce, to read logs and metadata from your orgs, signed in as the integration user.
- AWS License Manager Marketplace, to reserve and renew one unit per org.
- ipinfo.io, only if you turn on Look up sign-in locations with ipinfo.io in Setup → Alerts (off by default): the country and city of each new sign-in or download IP address, for Login Intelligence and Data Exfiltration. Only the IP address is sent, and answers are cached. An
IpInfoTokenonly raises ipinfo.io's rate limit. - Only if you configure them: your AI provider (for AI analysis), and Slack, Jira or Azure DevOps (for alerts and tickets).
11 · Troubleshooting
| Symptom | Likely cause and fix |
|---|---|
| Every WatchDog app shows "Authentication failed" | Check ApiGatewayUrl/api/licence/status in a browser. A licence problem shows there. Otherwise, check the Canvas App URL ends with / and the org was registered (Step 8). |
| An app shows "not in your plan" | The org has no package, or the package doesn't include that feature. See Setup → Plan. |
| Setup → Plan says "No unit available" | All your units of that package are assigned to other orgs. Buy more on AWS Marketplace, or change another org's package. |
| No logs arrive | The user causing the activity needs a Monitor Hub session, and Apex log polling must be saved in Setup. Logs from users without a session are deleted by default. |
| Data Exfiltration or Security Posture stays empty | They read Salesforce Event Monitoring logs; orgs without Event Monitoring have little or none to show. |
| No alarm emails | Confirm the subscription email AWS sent to AlarmEmail. |
| An app shows "Something went wrong. Reference: …" | Find the reference in the CloudWatch log group /watchdog/container/api (CloudWatch → Log groups → Search log group) for the full error, or send it to us with the time it happened. |
Monitor Hub or Setup reports INVALID_TYPE or "sObject type 'ApexLog' is not supported" | The integration user has a Salesforce Integration licence. Use a user with a full Salesforce licence (Step 7) and save it in Setup → General. |
| The Login Intelligence map is empty | Sign-in locations are off. Turn on Look up sign-in locations with ipinfo.io in Setup → Alerts; locations appear for sign-ins collected after that. |
| Registration fails | Open the CloudWatch log group /watchdog/container/register for the reason; most often the Consumer Key and Secret are swapped. |