# Maps

groundcover provides two map views for visualizing service dependencies and request flows: the **Map** page (standalone) and the **Map** tab on the **Traces** page. Both maps share the same core concepts but differ in which data they include.

## How the maps work

In both maps:

* **Nodes** represent a service or workload. A **workload** is a Kubernetes deployable unit that runs your application—for example, a Deployment, StatefulSet, or DaemonSet, or a custom resource such as Argo Rollouts and CloneSets—and is typically identified by the same name you see in the Workloads page and in filters.

Workloads are a representative aggregation of all the underlying pods. They are a non-customizable asset in groundcover, but you can enrich the data using **customEntityTags**.

* **Vertices** (the lines between nodes) represent a detected request dependency—for example, `nginx → main-api-web → postgres`.

The main difference is the **data source**:

|                 | Map page              | Traces → Map tab                                       |
| --------------- | --------------------- | ------------------------------------------------------ |
| **Data source** | eBPF trace spans only | All sources and span types (eBPF, OpenTelemetry, etc.) |

***

## Traces page map tab

Use **Traces → Map** when you want a dependency map that includes every span source (eBPF, OpenTelemetry, and others). You can filter by namespace, workload, status, and source in the Traces search and facets; the map reflects those filters.

* Each **node** is the client or server side of a span. Only spans that have both **client and server** set are shown.
* Each **vertex** between two nodes shows the type of spans shared between them (e.g. **HTTP**, **gRPC**, **PostgreSQL**).
* **Vertex color:**
  * **Green** — all span statuses on that connection are OK.
  * **Red** — at least one span status is Error.

<figure><img src="/files/Yzu97ZZoOvdvstX6Dn2E" alt="Traces page Map tab showing service dependency map with filters and vertex status"><figcaption><p>Traces page Map tab</p></figcaption></figure>

***

## Map page

The standalone **Map** page is built only from **eBPF** trace spans. Use it for a dependency view that reflects what the eBPF sensor sees (no OpenTelemetry or other sources).

* Each **node** is the client or server side of a span. Only spans that have both **client and server** set are shown. Nodes here are **eBPF-based only**.
* Each **vertex** between two nodes shows the type of spans shared between them (e.g. **HTTP**, **gRPC**, **Redis**).
* **Vertex color:**
  * **Green** — all span statuses on that connection are OK.
  * **Red** — at least one span status is Error.

<figure><img src="/files/tRL43d3kxqyC6R5Z6ZpA" alt="Map page showing eBPF-based service dependency map with connection and protocol filters"><figcaption><p>Map page</p></figcaption></figure>

***

## Summary

| Aspect           | Map page                                 | Traces → Map tab                        |
| ---------------- | ---------------------------------------- | --------------------------------------- |
| **Span source**  | eBPF only                                | All sources (eBPF, OpenTelemetry, etc.) |
| **Nodes**        | Client/server from span; eBPF spans only | Client/server from span; any source     |
| **Vertices**     | Span type between nodes (e.g. HTTP)      | Span type between nodes (e.g. HTTP)     |
| **Green vertex** | All span statuses OK                     | All span statuses OK                    |
| **Red vertex**   | Any span status Error                    | Any span status Error                   |


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.groundcover.com/use-groundcover/maps.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.