Grafana Cloud

Define service graph relationships

Asserts generates service graphs by analyzing time series data metrics. A service graph uses metrics like response time, uptime, latency, and error rates to determine the performance and health of the connections between services in your system.

There are two types of metrics-based relationships in a service graph:

  • Call relationship: Indicates when one service calls or invokes another service to carry out a task. Asserts uses asserts:relations:calls to define call relationships between services. The asserts:relation:calls metric measures the request rate per second. The Entity Explorer represents a call relationship with an arrow that connects the caller entity to the callee entity, and shows the number of calls per minute.
  • Route relationship: Indicates there is traffic flowing from the caller to the callee, but Asserts doesn’t determine whether it’s a service call or another type of call. The Entity Explorer shows a route relationship as an arrow from the caller to the callee. Asserts doesn’t consider the value of the metric asserts:relation:routes.

Asserts provides a library of rules that define service graph relationships, which you can view in the Entity Explorer. However, this library may not always have the specific rules you need for your situation. At times, you may not see the expected call or route relationship between entities.

The following instructions show you how to manually define call and route relationships in a service graph.

Before you begin

Before you begin, ensure the following:

  • You have experience writing Prometheus recording rules
  • You can identify the relationships between the caller and callee within metrics that have them.


Complete the following steps to define a service graph call or route relationship:

  1. Sign into Grafana Cloud and navigate to Asserts > Rules > Bring your own.

  2. Click the New rule file tab.

  3. Click New rule file.

  4. Copy and paste the following YAML template into the View/Edit YML file field.

       name: <NAME>
         - name: <GROUP NAME>
             - record: asserts:relation:calls
                 job: <CALLER JOB>
                 dst_job: <CALLEE JOB>
                 namespace: <CALLER NAMESPACE>
                 dst_namespace: <CALLEE NAMESPACE>
                 asserts_env: <ENVIRONMENT>
                 asserts_site: <SITE>
               labels: <LABELS>
  5. Use the following table to complete each YAML element:

    Placeholder variableDescription
    <NAME>Specify the name of the YAML file you are creating
    <GROUP NAME>Specify the name of the rule group
    <CALLER JOB>Matches the caller entity by its job property
    <CALLEE JOB>Matches the callee entity by its job property
    <CALLER NAMESPACE>Matches the caller entity by its namespace property, optional
    <CALLEE NAMESPACE>Matches the callee entity by its namespace property, optional
    <ENVIRONMENT>Matches the caller and callee entities’ environment property, optional
    <SITE>Matches the caller and callee entities’ environment property, optional
    <LABELS>Use to hard code job, dst_job, namespace, dst_namespace, and so on, optional


    Instead of using the job and dst_job fields, you can use service and dst_service.

    The metric value of query expression needs to be request rate per second, or in the case of defining asserts:relation:routes, it can be any positive value, such as 1.

  6. Click Save.

  7. Navigate back to the Entity Explorer to verify that the relationship is defined.