Sign In

Entity Relationships

Entity relationships define how services, applications, and infrastructure connect to and depend on each other.

Relationship Types

Type Outward Label Inward Label Use Case
depends_on Depends on Required by Service A requires Service B to function
parent_of Parent of Child of Hierarchical container (cluster → nodes)
child_of Child of Parent of Component within a parent
related_to Related to Related to General association
backed_by Backed by Powers Service powered by infrastructure
supports Supports Supported by Infrastructure supports a service

Directional Labels

Relationships have direction. The label displayed depends on which entity you’re viewing:

Viewing Relationship Shows As
Payment Service depends_on → Database “Depends on Database”
Database ← depends_on Payment Service “Required by Payment Service”

Both entities display the relationship with appropriate context.

Creating Relationships

From any entity detail page:

  1. Locate the Entity Relationships section
  2. Click Link Catalog Entity
  3. Select a Relationship Type from the dropdown
  4. Select a Target Entity from the entity picker
  5. Click Link

To add multiple relationships at once:

  1. After selecting the first relationship, click Add Another Linked Entity
  2. Select additional relationship types and target entities
  3. Click Link to save all relationships

Viewing Relationships

Each entity’s detail page shows relationships in two contexts:

Outward relationships - What this entity depends on or relates to

Inward relationships - What depends on or relates to this entity

Relationships display:

  • Relationship type with directional label
  • Target entity name
  • Entity type
  • Remove button

Removing Relationships

To remove a relationship:

  1. Navigate to the entity detail page
  2. Find the relationship in the Entity Relationships section
  3. Click the X button on the relationship
  4. Confirm the removal

The relationship is removed from both entities.

Common Patterns

Microservices Architecture

Frontend → depends_on → API Gateway
API Gateway → depends_on → User Service
API Gateway → depends_on → Order Service
User Service → backed_by → User Database
Order Service → backed_by → Order Database

Database Clustering

Application → depends_on → Database Load Balancer
Database Load Balancer → parent_of → Primary Database
Database Load Balancer → parent_of → Read Replica 1
Database Load Balancer → parent_of → Read Replica 2

Multi-Region Deployment

Global Load Balancer → parent_of → US-East LB
Global Load Balancer → parent_of → EU-West LB
US-East LB → parent_of → US-East App Cluster
EU-West LB → parent_of → EU-West App Cluster

Best Practices

Start with critical paths

  1. Map customer-facing services first
  2. Add their immediate dependencies
  3. Continue mapping transitively
  4. Document infrastructure last

Choose specific types

  • Use depends_on for hard dependencies
  • Use related_to for loose coupling
  • Use backed_by for infrastructure

Keep relationships current

  • Update when deploying new services
  • Remove when decommissioning
  • Review periodically for accuracy

Circular Dependency Prevention

Upstat prevents circular dependencies. You cannot create a relationship chain where Entity A depends on Entity B, which depends on Entity A.

If you attempt to create a circular dependency, the operation fails with an error message.