Service Registry

Service Registry

The Service Registry maps your monitoring alerts to your actual infrastructure services — the repositories where the code lives and the platforms where it runs. When the AI Chat investigates an alert for a registered service, it automatically knows which GitHub repo to search and which deploy platform to target, producing more specific and actionable guidance.

Why It Matters

Without the Service Registry, the AI Chat can analyze alert text and metrics but has no connection to your codebase or deployment infrastructure. With it, the AI can:

• Suggest gh search commands scoped to the correct repository
• Generate deployment-specific CLI commands (e.g., railway logs vs. kubectl logs)
• Reference the right cluster, project, or namespace in its instructions
• Recommend code paths to investigate based on the service’s language and structure

Configuration

The Service Registry is configured in the Chrome extension’s Options page. Each entry maps a service name (as it appears in your monitoring platform alerts) to its code and deployment details.

1. Open Extension Options

   Right-click the Overwatch extension icon in Chrome and select Options, or click the extension icon and then the settings gear.

2. Scroll to Service Registry

   The Service Registry section is below the environment configuration fields (AWS, Kubernetes, etc.).

3. Add a Service

   Click Add Service to create a new entry.

4. Fill in the Service Details

   Configure each field as described below, then click Save Settings.

Service Entry Fields

For each service, you configure the following fields:

Field	Description	Example
Service Name	The name as it appears in your monitoring platform alerts. Used for matching.	quickshop-api
GitHub Repo	The repository URL or owner/repo shorthand where the service’s code lives.	acme-corp/quickshop-api
Deploy Platform	The hosting platform where this service runs. Selected from a dropdown.	Railway
Deploy Identifier	Platform-specific identifier used to target the correct deployment.	quickshop/api-production
Language	The primary programming language of the service.	Python
Code Paths	Key source directories within the repository to focus investigation on.	src/, app/
Notes	Free-text description of the service for additional AI context.	FastAPI backend, uses Redis cache

Tip

The Service Name must match exactly how the service is identified in your monitoring alerts. If Datadog shows alerts for quickshop-api, use that exact string. Matching is case-insensitive as a fallback, but exact matches are preferred.

Example Configuration

A fully configured service entry for a Python API deployed on Railway:

{
  "quickshop-api": {
    "githubRepo": "acme-corp/quickshop-api",
    "deployPlatform": "railway",
    "deployIdentifier": "quickshop/api-production",
    "language": "python",
    "codePaths": "app/, services/",
    "notes": "FastAPI backend with PostgreSQL and Redis. Handles order processing."
  }
}

Platform Support

The Deploy Platform dropdown includes the following options. The Deploy Identifier format varies by platform.

Platform	Deploy Identifier Format	Example
Railway	Project name / Service name	quickshop/api-production
AWS ECS	Cluster / Service	prod-cluster/quickshop-api-service
AWS Lambda	Function name	quickshop-order-processor
Kubernetes	Context / Namespace / Deployment	prod-cluster/default/quickshop-api
GCP Cloud Run	Project / Service / Region	acme-prod/quickshop-api/us-central1
Azure Container Apps	Resource Group / App name	acme-rg/quickshop-api
Docker Compose	Compose project / Service name	quickshop/api
Vercel	Project name	quickshop-frontend
Fly.io	App name	quickshop-api
Other	Free-form identifier	Any string meaningful to your setup

Note

The Deploy Identifier is passed to the AI as context. It does not need to be machine-parseable — the AI uses it to generate appropriate CLI commands for the selected platform.

How It Enriches AI Chat

When an alert fires for a service that is registered in the Service Registry, the extension automatically includes the service configuration in the AI Chat context. This changes the AI’s behavior in several concrete ways.

Without Service Registry

The AI sees only the alert payload:

“Alert: High error rate on quickshop-api (5xx errors > 5%)”

The AI provides general troubleshooting advice but cannot reference your specific infrastructure.

With Service Registry

The AI knows the full service context:

Service: quickshop-api Repo: acme-corp/quickshop-api Platform: Railway (quickshop/api-production) Language: Python Code Paths: app/, services/

This allows the AI to generate targeted recommendations:

Code Investigation

# Search for error handling in the relevant service
gh search code "500" --repo acme-corp/quickshop-api --path app/

# Look at recent commits that may have introduced the issue
gh api repos/acme-corp/quickshop-api/commits --jq '.[0:5] | .[].commit.message'

Railway Commands

# Check recent deploy logs
railway logs --project quickshop --service api-production

# View recent deployments
railway status --project quickshop

Kubernetes Commands

# Get pod logs for the failing service
kubectl logs -l app=quickshop-api -n default --context prod-cluster --tail=100

# Check pod status
kubectl get pods -l app=quickshop-api -n default --context prod-cluster

AWS ECS Commands

# View service events
aws ecs describe-services \
  --cluster prod-cluster \
  --services quickshop-api-service \
  --query 'services[0].events[:5]'

# Check task logs
aws logs tail /ecs/quickshop-api --follow

Context Flow

The service registry data flows through the system as follows:

1. An alert fires on your monitoring platform (Datadog, Grafana, PagerDuty, etc.)
2. The extension detects the alert and extracts the service name
3. The UserProfileService looks up the service name in the registry via getServiceConfig()
4. If a match is found, the service configuration is included in the getContextForAPI() payload
5. The AI Chat receives the enriched context and tailors its response accordingly

Migration from Legacy Configuration

Earlier versions of the extension used Railway-specific fields (railwayProject, railwayService) at the top level of the service registry entry. These legacy fields are automatically migrated to the platform-agnostic format when the Options page loads.

Legacy format (pre-v3.2):

{
  "quickshop-api": {
    "githubRepo": "acme-corp/quickshop-api",
    "railwayProject": "quickshop",
    "railwayService": "api-production"
  }
}

Current format (v3.2+):

{
  "quickshop-api": {
    "githubRepo": "acme-corp/quickshop-api",
    "deployPlatform": "railway",
    "deployIdentifier": "quickshop/api-production"
  }
}

Caution

No manual action is required. The migration happens automatically when you open the Options page. Your old configuration values are preserved and mapped to the new deployPlatform and deployIdentifier fields. However, you should review your entries after migration to confirm the values are correct.

Best Practices

Register all services that generate alerts. If a service sends alerts through your monitoring platform and those alerts reach Overwatch, register it. Even partial configuration (just the GitHub repo) is better than none.

Keep GitHub repo URLs current. If you rename or move a repository, update the service registry. The AI uses these URLs to generate gh CLI commands and search queries.

Use descriptive notes. The Notes field is passed directly to the AI as context. Include details like the tech stack, key dependencies, or common failure modes. For example: “FastAPI backend, uses Redis for session cache, PostgreSQL for persistence. Known issue: connection pool exhaustion under load.”

Match service names exactly. The service name in the registry must match what appears in your monitoring alerts. Check your alert payloads to confirm the exact string used.

Configure code paths for large repositories. If a repository contains multiple services or has a deep directory structure, specify the relevant source paths (e.g., backend/app/, backend/services/). This helps the AI narrow its code search suggestions.

Review entries after importing settings. When you import a settings file from another team member or environment, verify that the service registry entries reference the correct repositories and deploy identifiers for your context.

Next Steps

• Chrome Extension Configuration — Complete extension settings reference
• Chrome Extension Workflows — Common usage workflows with the extension
• Integrations — Connect monitoring platforms that generate alerts

---

Related Documentation:

• Chrome Extension Installation
• Chrome Extension Configuration
• Organization Setup

---

Document version: 1.0 — Initial release