Merge pull request #404 from go-faster/feat/update-tempo-api

feat(oas): update Tempo API

_oas/tempo.yml

@@ -1,7 +1,7 @@
 openapi: 3.0.3
 info:
   title: Grafana Tempo 'query-frontend' API
-  version: 2.1.0
+  version: 2.4.0
 externalDocs:
   description: Tempo API reference
   url: https://grafana.com/docs/tempo/latest/api_docs
@@ -33,12 +33,14 @@ paths:
           schema:
             type: string
           description: TraceID to query.
+
         - name: start
           in: query
           schema:
             type: integer
             format: unix-seconds
           description: Along with `end` define a time range from which traces should be returned.
+
         - name: end
           in: query
           schema:
@@ -116,6 +118,13 @@ paths:
             Providing both `start` and `end` will change the way that Tempo searches.
             If the parameters are not provided, then Tempo will search the recent trace data stored in the ingesters.
             If the parameters are provided, it will search the backend as well.
+
+        - name: spss
+          in: query
+          schema:
+            type: integer
+          description: |
+            Limit the number of spans per span-set. Default value is 3.
       responses:
         200:
           $ref: "#/components/responses/Search"
@@ -126,6 +135,30 @@ paths:
     get:
       operationId: searchTags
       description: This endpoint retrieves all discovered tag names that can be used in search.
+      parameters:
+        - name: scope
+          in: query
+          schema:
+            $ref: "#/components/schemas/TagScope"
+          description: |
+            Specifies the scope of the tags, this is an optional parameter, if not specified it means all scopes.
+
+        - name: start
+          in: query
+          schema:
+            type: integer
+            format: unix-seconds
+          description: |
+            Along with `end` define a time range from which tags should be returned.
+
+        - name: end
+          in: query
+          schema:
+            type: integer
+            format: unix-seconds
+          description: |
+            Along with `start` define a time range from which tags should be returned.
+            Providing both `start` and `end` includes blocks for the specified time range only.
       responses:
         200:
           $ref: "#/components/responses/SearchTags"
@@ -143,29 +176,123 @@ paths:
           schema:
             type: string
           description: Tag name.
+
+        - name: q
+          in: query
+          schema:
+            type: string
+          description: |
+            If provided, the tag values returned by the API are filtered to only return values seen on spans matching your filter parameters.
+            Queries can be incomplete: for example, `{ .cluster = }`. Tempo extracts only the valid matchers and build a valid query.
+
+            Only queries with a single selector `{}`` and AND `&&` operators are supported.
+
+            - Example supported: `{ .cluster = "us-east-1" && .service = "frontend" }`
+            - Example unsupported: `{ .cluster = "us-east-1" || .service = "frontend" } && { .cluster = "us-east-2" }`
+
+        - name: start
+          in: query
+          schema:
+            type: integer
+            format: unix-seconds
+          description: |
+            Along with `end` define a time range from which tags should be returned.
+
+        - name: end
+          in: query
+          schema:
+            type: integer
+            format: unix-seconds
+          description: |
+            Along with `start` define a time range from which tags should be returned.
+            Providing both `start` and `end` includes blocks for the specified time range only.
       responses:
         200:
           $ref: "#/components/responses/SearchTagValues"
         default:
           $ref: "#/components/responses/Error"
 
-  /api/v2/search/tag/{tag_name}/values:
+  /api/v2/search/tag/{attribute_selector}/values:
     get:
       operationId: searchTagValuesV2
       description: This endpoint retrieves all discovered values and their data types for the given TraceQL identifier.
       parameters:
-        - name: tag_name
+        - name: attribute_selector
           in: path
           required: true
           schema:
             type: string
-          description: Tag name.
+          description: TraceQL attribute selector (`.service.name`, `resource.service.name`, etc.).
+
+        - name: q
+          in: query
+          schema:
+            type: string
+          description: |
+            If provided, the tag values returned by the API are filtered to only return values seen on spans matching your filter parameters.
+            Queries can be incomplete: for example, `{ .cluster = }`. Tempo extracts only the valid matchers and build a valid query.
+
+            Only queries with a single selector `{}`` and AND `&&` operators are supported.
+
+            - Example supported: `{ .cluster = "us-east-1" && .service = "frontend" }`
+            - Example unsupported: `{ .cluster = "us-east-1" || .service = "frontend" } && { .cluster = "us-east-2" }`
+
+        - name: start
+          in: query
+          schema:
+            type: integer
+            format: unix-seconds
+          description: |
+            Along with `end` define a time range from which tags should be returned.
+
+        - name: end
+          in: query
+          schema:
+            type: integer
+            format: unix-seconds
+          description: |
+            Along with `start` define a time range from which tags should be returned.
+            Providing both `start` and `end` includes blocks for the specified time range only.
       responses:
         200:
           $ref: "#/components/responses/SearchTagValuesV2"
         default:
           $ref: "#/components/responses/Error"
 
+  /api/v2/search/tags:
+    get:
+      operationId: searchTagsV2
+      description: This endpoint retrieves all discovered tag names that can be used in search.
+      parameters:
+        - name: scope
+          in: query
+          schema:
+            $ref: "#/components/schemas/TagScope"
+          description: |
+            Specifies the scope of the tags, this is an optional parameter, if not specified it means all scopes.
+
+        - name: start
+          in: query
+          schema:
+            type: integer
+            format: unix-seconds
+          description: |
+            Along with `end` define a time range from which tags should be returned.
+
+        - name: end
+          in: query
+          schema:
+            type: integer
+            format: unix-seconds
+          description: |
+            Along with `start` define a time range from which tags should be returned.
+            Providing both `start` and `end` includes blocks for the specified time range only.
+      responses:
+        200:
+          $ref: "#/components/responses/SearchTagsV2"
+        default:
+          $ref: "#/components/responses/Error"
+
 components:
   responses:
     Error:
@@ -201,6 +328,12 @@ components:
         "application/json":
           schema:
             $ref: "#/components/schemas/TagValues"
+    SearchTagsV2:
+      description: Search tags result
+      content:
+        "application/json":
+          schema:
+            $ref: "#/components/schemas/TagNamesV2"
     SearchTagValuesV2:
       description: Search tag values result
       content:
@@ -354,6 +487,24 @@ components:
           items:
             type: string
 
+    TagNamesV2:
+      type: object
+      properties:
+        scopes:
+          type: array
+          items:
+            $ref: "#/components/schemas/ScopeTags"
+    ScopeTags:
+      type: object
+      required: [name]
+      properties:
+        name:
+          $ref: "#/components/schemas/TagScope"
+        tags:
+          type: array
+          items:
+            type: string
+
     TagValuesV2:
       type: object
       properties:
@@ -372,5 +523,13 @@ components:
         value:
           type: string
 
+    TagScope:
+      type: string
+      enum:
+        - "span"
+        - "resource"
+        - "intrinsic"
+        - "none"
+
     Error:
       type: string

cmd/oteldb/app.go

@@ -154,7 +154,7 @@ func (app *App) trySetupTempo() error {
 	engine := traceqlengine.NewEngine(app.traceQuerier, traceqlengine.Options{
 		TracerProvider: app.metrics.TracerProvider(),
 	})
-	tempo := tempohandler.NewTempoAPI(q, engine)
+	tempo := tempohandler.NewTempoAPI(q, engine, tempohandler.TempoAPIOptions{})
 
 	s, err := tempoapi.NewServer(tempo,
 		tempoapi.WithTracerProvider(app.metrics.TracerProvider()),

integration/logger.go

@@ -0,0 +1,49 @@
+package integration
+
+import (
+	"testing"
+
+	"go.uber.org/zap"
+	"go.uber.org/zap/zapcore"
+	"go.uber.org/zap/zaptest"
+)
+
+// Logger creates a new [zap.Logger] to use in tests.
+func Logger(t *testing.T) *zap.Logger {
+	return zaptest.NewLogger(t, zaptest.WrapOptions(zap.WrapCore(wrapTestLogger)))
+}
+
+func wrapTestLogger(core zapcore.Core) zapcore.Core {
+	return &filterCore{core: core}
+}
+
+type filterCore struct {
+	core zapcore.Core
+}
+
+var _ zapcore.Core = (*filterCore)(nil)
+
+func (c *filterCore) Enabled(l zapcore.Level) bool {
+	return c.core.Enabled(l)
+}
+
+func (c *filterCore) With(fields []zapcore.Field) zapcore.Core {
+	return &filterCore{
+		core: c.core.With(fields),
+	}
+}
+
+func (c *filterCore) Check(e zapcore.Entry, ce *zapcore.CheckedEntry) *zapcore.CheckedEntry {
+	if ce == nil || ce.LoggerName == "ch" {
+		return ce
+	}
+	return c.core.Check(e, ce)
+}
+
+func (c *filterCore) Write(e zapcore.Entry, fields []zapcore.Field) error {
+	return c.core.Write(e, fields)
+}
+
+func (c *filterCore) Sync() error {
+	return c.core.Sync()
+}

integration/lokie2e/ch_test.go

@@ -14,7 +14,6 @@ import (
 	"github.com/go-faster/sdk/zctx"
 	"github.com/stretchr/testify/require"
 	"github.com/testcontainers/testcontainers-go"
-	"go.uber.org/zap/zaptest"
 
 	"github.com/go-faster/oteldb/integration"
 	"github.com/go-faster/oteldb/internal/chstorage"
@@ -91,6 +90,6 @@ func TestCH(t *testing.T) {
 	})
 	require.NoError(t, err)
 
-	ctx = zctx.Base(ctx, zaptest.NewLogger(t))
+	ctx = zctx.Base(ctx, integration.Logger(t))
 	runTest(ctx, t, provider, inserter, querier, querier)
 }

integration/prome2e/ch_test.go

@@ -10,6 +10,7 @@ import (
 	"github.com/ClickHouse/ch-go/chpool"
 	"github.com/cenkalti/backoff/v4"
 	"github.com/go-faster/errors"
+	"github.com/go-faster/sdk/zctx"
 	"github.com/google/uuid"
 	"github.com/stretchr/testify/require"
 	"github.com/testcontainers/testcontainers-go"
@@ -76,5 +77,6 @@ func TestCH(t *testing.T) {
 	querier, err := chstorage.NewQuerier(c, chstorage.QuerierOptions{Tables: tables})
 	require.NoError(t, err)
 
+	ctx = zctx.Base(ctx, integration.Logger(t))
 	runTest(ctx, t, inserter, querier, querier)
 }

integration/tempoe2e/ch_test.go

@@ -10,6 +10,7 @@ import (
 	"github.com/ClickHouse/ch-go/chpool"
 	"github.com/cenkalti/backoff/v4"
 	"github.com/go-faster/errors"
+	"github.com/go-faster/sdk/zctx"
 	"github.com/google/uuid"
 	"github.com/stretchr/testify/require"
 	"github.com/testcontainers/testcontainers-go"
@@ -76,5 +77,6 @@ func TestCH(t *testing.T) {
 	querier, err := chstorage.NewQuerier(c, chstorage.QuerierOptions{Tables: tables})
 	require.NoError(t, err)
 
+	ctx = zctx.Base(ctx, integration.Logger(t))
 	runTest(ctx, t, inserter, querier, querier)
 }