Skip to content

:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.

feat(tracing): group span aggregation by http endpoint (#125351)

Jon McCallum8a53c8ec5c82
diff --git a/frontend/src/queries/schema.json b/frontend/src/queries/schema.json
index 51a8dc8c5cb5..a6e640c560a8 100644
--- a/frontend/src/queries/schema.json
+++ b/frontend/src/queries/schema.json
@@ -55317,6 +55317,10 @@
"filterGroup": {
"$ref": "#/definitions/PropertyGroupFilter"
},
+ "groupByEndpoint": {
+ "description": "Group HTTP server spans by `METHOD route` in place of the span name. Spans without a route keep their name. Spans that are not HTTP server spans are left out.",
+ "type": "boolean"
+ },
"includeImpact": {
"description": "Also aggregate sessions and people per operation. Off by default: it reads the attribute maps.",
"type": "boolean"
diff --git a/frontend/src/queries/schema/schema-general.ts b/frontend/src/queries/schema/schema-general.ts
index de8e5de4cdc8..6e3db686c653 100644
--- a/frontend/src/queries/schema/schema-general.ts
+++ b/frontend/src/queries/schema/schema-general.ts
@@ -5351,6 +5351,11 @@ export interface TraceSpansAggregationQuery extends DataNode<TraceSpansAggregati
serviceNames?: string[]
/** Also aggregate sessions and people per operation. Off by default: it reads the attribute maps. */
includeImpact?: boolean
+ /**
+ * Group HTTP server spans by `METHOD route` in place of the span name. Spans without a route keep their name.
+ * Spans that are not HTTP server spans are left out.
+ */
+ groupByEndpoint?: boolean
}
export interface TraceSpansAggregationQueryResponse extends AnalyticsQueryResponseBase {
diff --git a/posthog/schema.py b/posthog/schema.py
index 6becd2c74672..0ee346791a8b 100644
--- a/posthog/schema.py
+++ b/posthog/schema.py
@@ -31584,6 +31584,14 @@ class TraceSpansAggregationQuery(BaseModel):
)
dateRange: DateRange
filterGroup: PropertyGroupFilter | None = None
+ groupByEndpoint: bool | None = Field(
+ default=None,
+ description=(
+ "Group HTTP server spans by `METHOD route` in place of the span name. Spans"
+ " without a route keep their name. Spans that are not HTTP server spans are"
+ " left out."
+ ),
+ )
includeImpact: bool | None = Field(
default=None,
description=("Also aggregate sessions and people per operation. Off by default: it reads the attribute maps."),
diff --git a/products/tracing/backend/aggregation_query_runner.py b/products/tracing/backend/aggregation_query_runner.py
index 3370429639cb..12d5d0ce2ddc 100644
--- a/products/tracing/backend/aggregation_query_runner.py
+++ b/products/tracing/backend/aggregation_query_runner.py
@@ -63,7 +63,7 @@ from .logic import (
with_span_attribute_type_suffix,
)
from .models import TracingIdentityAttributeKeys
-from .span_identity import identity_value_expr
+from .span_identity import identity_value_expr, str_attr_field
if TYPE_CHECKING:
from posthog.models import Team, User
@@ -277,8 +277,14 @@ class TraceSpansAggregationQueryRunner(_SpanAggregationMixin, AnalyticsQueryRunn
def _build_query(self, query_date_range: QueryDateRange) -> ast.SelectQuery:
# Single table scan plus hash aggregate. Cheap enough to run unscoped.
+ where = self._where_without_date_range()
+ group_name: ast.Expr = ast.Field(chain=["name"])
+ if self.query.groupByEndpoint:
+ where = ast.And(exprs=[where, _endpoint_scope_expr()])
+ group_name = _endpoint_name_expr()
placeholders: dict[str, ast.Expr] = {
- "where": self._where_without_date_range(),
+ "where": where,
+ "group_name": group_name,
"limit": ast.Constant(value=self._limit),
"offset": ast.Constant(value=self._offset),
**query_date_range.to_placeholders(),
@@ -302,7 +308,7 @@ class TraceSpansAggregationQueryRunner(_SpanAggregationMixin, AnalyticsQueryRunn
"""
SELECT
service_name,
- name,
+ {group_name} AS group_name,
count() AS count,
sum(duration_nano) AS total_duration_nano,
avg(duration_nano) AS avg_duration_nano,
@@ -317,7 +323,7 @@ class TraceSpansAggregationQueryRunner(_SpanAggregationMixin, AnalyticsQueryRunn
+ """
AND timestamp >= {date_from}
AND timestamp < {date_to}
- GROUP BY service_name, name
+ GROUP BY service_name, group_name
ORDER BY total_duration_nano DESC
LIMIT {limit}
OFFSET {offset}
@@ -353,6 +359,30 @@ class TraceSpansAggregationQueryRunner(_SpanAggregationMixin, AnalyticsQueryRunn
return response
+def _http_method_expr() -> ast.Expr:
+ # OTel renamed `http.method` to `http.request.method`; SDKs in the wild send either.
+ return parse_expr(
+ "coalesce(nullIf({new}, ''), nullIf({old}, ''))",
+ placeholders={"new": str_attr_field("http.request.method"), "old": str_attr_field("http.method")},
+ )
+
+
+def _endpoint_scope_expr() -> ast.Expr:
+ # Server spans alone include queue consumers and Temporal activities, which carry no HTTP method.
+ return parse_expr("kind = 2 AND {method} IS NOT NULL", placeholders={"method": _http_method_expr()})
+
+
+def _endpoint_name_expr() -> ast.Expr:
+ # Instrumentations may name a span after the raw path or the bare method, so the route is the stable key.
+ return parse_expr(
+ "if({route} IS NOT NULL, concat({method}, ' ', {route}), name)",
+ placeholders={
+ "route": ast.Call(name="nullIf", args=[str_attr_field("http.route"), ast.Constant(value="")]),
+ "method": _http_method_expr(),
+ },
+ )
+
+
def _annotate_calls_per_parent_invocation(rows: list[SpanTreeNode]) -> None:
"""Set each edge's child-calls-per-parent-invocation ratio, in place.
diff --git a/products/tracing/backend/logic.py b/products/tracing/backend/logic.py
index de4d513bf8f5..3b332adad16f 100644
--- a/products/tracing/backend/logic.py
+++ b/products/tracing/backend/logic.py
@@ -1419,6 +1419,7 @@ def run_aggregation_query(
limit: int | None = None,
offset: int = 0,
include_impact: bool = False,
+ group_by_endpoint: bool = False,
) -> TraceSpansAggregationQueryResponse | CachedTraceSpansAggregationQueryResponse:
"""Facade-friendly entry point for running a flat span aggregation query."""
# The runners import `translate_span_filter` from this module, so a module-level import here is circular.
@@ -1434,6 +1435,7 @@ def run_aggregation_query(
filterGroup=filter_group,
serviceNames=service_names,
includeImpact=include_impact,
+ groupByEndpoint=group_by_endpoint,
)
runner = TraceSpansAggregationQueryRunner(
query,
diff --git a/products/tracing/backend/tests/test_aggregation_query_runner.py b/products/tracing/backend/tests/test_aggregation_query_runner.py
index 649e532fa132..4c41ebe1b390 100644
--- a/products/tracing/backend/tests/test_aggregation_query_runner.py
+++ b/products/tracing/backend/tests/test_aggregation_query_runner.py
@@ -256,3 +256,61 @@ class TestTraceSpansTreePercentiles(_TraceSpansTestBase):
)
edge = next(n for n in response.results if n.name == self.CHILD_NAME)
self.assertAlmostEqual(getattr(edge, field), expected_nano, delta=MS_TO_NANO)
+
+
+class TestTraceSpansAggregationGroupByEndpoint(_TraceSpansTestBase):
+ SERVICE = "api"
+ SERVER, CLIENT = 2, 3
+ SPANS = [
+ ("/users/1", SERVER, {"http.method": "GET", "http.route": "/users/{id}"}),
+ ("/users/2", SERVER, {"http.request.method": "GET", "http.route": "/users/{id}"}),
+ ("GET", SERVER, {"http.method": "GET", "http.route": "/orders"}),
+ ("GET", SERVER, {"http.method": "GET", "http.route": "/items"}),
+ ("GET /health", SERVER, {"http.method": "GET"}),
+ ("RunActivity:sync", SERVER, {}),
+ ("GET", CLIENT, {"http.method": "GET", "http.route": "/upstream"}),
+ ]
+
+ @classmethod
+ def setUpTestData(cls):
+ super().setUpTestData()
+ cls._recreate_trace_spans_tables()
+
+ base = dt.datetime(2026, 6, 2, 8, 0, 0)
+ ts_str = base.strftime("%Y-%m-%d %H:%M:%S.%f")
+ end_str = (base + dt.timedelta(milliseconds=10)).strftime("%Y-%m-%d %H:%M:%S.%f")
+ rows: list[str] = []
+ for i, (name, kind, attributes) in enumerate(cls.SPANS):
+ attribute_map = "map(" + ", ".join(f"'{key}__str', '{value}'" for key, value in attributes.items()) + ")"
+ rows.append(
+ f"('019e8762-0000-0000-0000-{i:012d}', {cls.team.id}, '{_b64(i.to_bytes(16, 'big'))}', "
+ f"'{_b64((100 + i).to_bytes(8, 'big'))}', '', '{name}', {kind}, '{ts_str}', '{end_str}', "
+ f"'{ts_str}', 0, '{cls.SERVICE}', {attribute_map})"
+ )
+ sync_execute(
+ "INSERT INTO trace_spans (uuid, team_id, trace_id, span_id, parent_span_id, name, kind, "
+ "timestamp, end_time, observed_timestamp, status_code, service_name, attributes_map_str) VALUES "
+ + ",".join(rows)
+ )
+
+ @parameterized.expand(
+ [
+ (
+ "by_span_name",
+ False,
+ {("/users/1", 1), ("/users/2", 1), ("GET", 3), ("GET /health", 1), ("RunActivity:sync", 1)},
+ ),
+ (
+ "by_endpoint",
+ True,
+ {("GET /users/{id}", 2), ("GET /orders", 1), ("GET /items", 1), ("GET /health", 1)},
+ ),
+ ]
+ )
+ def test_rows(self, _name, group_by_endpoint, expected):
+ response = run_aggregation_query(
+ team=self.team,
+ date_range=DateRange(date_from=DATE_FROM, date_to=DATE_TO),
+ group_by_endpoint=group_by_endpoint,
+ )
+ self.assertEqual({(row.name, row.count) for row in response.results}, expected)
diff --git a/services/mcp/src/api/generated.ts b/services/mcp/src/api/generated.ts
index 8c2024ff6721..e9b540aaa761 100644
--- a/services/mcp/src/api/generated.ts
+++ b/services/mcp/src/api/generated.ts
@@ -62337,6 +62337,8 @@ export namespace Schemas {
compareFilter?: CompareFilter | null;
dateRange: DateRange;
filterGroup?: PropertyGroupFilter | null;
+ /** Group HTTP server spans by `METHOD route` in place of the span name. Spans without a route keep their name. Spans that are not HTTP server spans are left out. */
+ groupByEndpoint?: boolean | null;
/** Also aggregate sessions and people per operation. Off by default: it reads the attribute maps. */
includeImpact?: boolean | null;
kind?: 'TraceSpansAggregationQuery';