feat(otel): set ate.* actor identity on router and ateapi spans

Author: krisztianfekete

cmd/ateapi/internal/controlapi/create_actor.go

@@ -33,6 +33,7 @@ func (s *Service) CreateActor(ctx context.Context, req *ateapipb.CreateActorRequ
 	if err := validateCreateActorRequest(req); err != nil {
 		return nil, err
 	}
+	setSpanActorRefIdentity(ctx, req.GetActorRef().GetAtespace(), req.GetActorRef().GetName())
 	_, err := s.actorTemplateLister.ActorTemplates(req.GetActorTemplateNamespace()).Get(req.GetActorTemplateName())
 	if err != nil {
 		if k8serrors.IsNotFound(err) {
@@ -69,6 +70,7 @@ func (s *Service) CreateActor(ctx context.Context, req *ateapipb.CreateActorRequ
 		return nil, fmt.Errorf("while recording actor: %w", err)
 	}
 
+	setSpanActorIdentity(ctx, stored)
 	return &ateapipb.CreateActorResponse{
 		Actor: stored,
 	}, nil

cmd/ateapi/internal/controlapi/delete_actor.go

@@ -31,6 +31,7 @@ func (s *Service) DeleteActor(ctx context.Context, req *ateapipb.DeleteActorRequ
 	if err := validateDeleteActorRequest(req); err != nil {
 		return nil, err
 	}
+	setSpanActorRefIdentity(ctx, req.GetActorRef().GetAtespace(), req.GetActorRef().GetName())
 
 	if err := s.persistence.DeleteActor(ctx, req.GetActorRef().GetAtespace(), req.GetActorRef().GetName()); err != nil {
 		if errors.Is(err, store.ErrNotFound) {

cmd/ateapi/internal/controlapi/pause_actor.go

@@ -30,6 +30,7 @@ func (s *Service) PauseActor(ctx context.Context, req *ateapipb.PauseActorReques
 	if err := validatePauseActorRequest(req); err != nil {
 		return nil, err
 	}
+	setSpanActorRefIdentity(ctx, req.GetActorRef().GetAtespace(), req.GetActorRef().GetName())
 
 	actor, err := s.actorWorkflow.PauseActor(ctx, req.GetActorRef().GetAtespace(), req.GetActorRef().GetName())
 	if err != nil {
@@ -42,6 +43,7 @@ func (s *Service) PauseActor(ctx context.Context, req *ateapipb.PauseActorReques
 		return nil, err
 	}
 
+	setSpanActorIdentity(ctx, actor)
 	return &ateapipb.PauseActorResponse{Actor: actor}, nil
 }
 

cmd/ateapi/internal/controlapi/resume_actor.go

@@ -30,6 +30,7 @@ func (s *Service) ResumeActor(ctx context.Context, req *ateapipb.ResumeActorRequ
 	if err := validateResumeActorRequest(req); err != nil {
 		return nil, err
 	}
+	setSpanActorRefIdentity(ctx, req.GetActorRef().GetAtespace(), req.GetActorRef().GetName())
 
 	actor, err := s.actorWorkflow.ResumeActor(ctx, req.GetActorRef().GetAtespace(), req.GetActorRef().GetName(), req.GetBoot())
 	if err != nil {
@@ -42,6 +43,7 @@ func (s *Service) ResumeActor(ctx context.Context, req *ateapipb.ResumeActorRequ
 		return nil, err
 	}
 
+	setSpanActorIdentity(ctx, actor)
 	return &ateapipb.ResumeActorResponse{Actor: actor}, nil
 }
 

cmd/ateapi/internal/controlapi/span_identity.go

@@ -0,0 +1,36 @@
+// Copyright 2026 Google LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package controlapi
+
+import (
+	"context"
+
+	"go.opentelemetry.io/otel/trace"
+
+	"github.com/agent-substrate/substrate/internal/ateattr"
+	"github.com/agent-substrate/substrate/pkg/proto/ateapipb"
+)
+
+// setSpanActorIdentity annotates the RPC's server span (from ctx) with the
+// actor's full identity. A no-op when ctx carries no recording span.
+func setSpanActorIdentity(ctx context.Context, a *ateapipb.Actor) {
+	trace.SpanFromContext(ctx).SetAttributes(ateattr.ActorIdentity(a)...)
+}
+
+// setSpanActorRefIdentity is setSpanActorIdentity for the identity subset known
+// before the Actor record resolves, so a failed lookup still carries who/where.
+func setSpanActorRefIdentity(ctx context.Context, atespace, actorID string) {
+	trace.SpanFromContext(ctx).SetAttributes(ateattr.ActorRefIdentity(atespace, actorID)...)
+}

cmd/ateapi/internal/controlapi/span_identity_test.go

@@ -0,0 +1,145 @@
+// Copyright 2026 Google LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package controlapi
+
+import (
+	"context"
+	"testing"
+
+	"go.opentelemetry.io/otel"
+	"go.opentelemetry.io/otel/attribute"
+	sdktrace "go.opentelemetry.io/otel/sdk/trace"
+	"go.opentelemetry.io/otel/sdk/trace/tracetest"
+
+	"github.com/agent-substrate/substrate/internal/ateattr"
+	"github.com/agent-substrate/substrate/pkg/proto/ateapipb"
+)
+
+// The functional harness registers no otelgrpc StatsHandler, so there is no
+// server span on the client path. These tests instead call the Service methods
+// in-process under a self-provided recording root span, which stands in for the
+// span the otelgrpc handler injects in production and exercises the same
+// trace.SpanFromContext(ctx).SetAttributes path.
+func installSpanRecorder(t *testing.T) *tracetest.SpanRecorder {
+	t.Helper()
+	sr := tracetest.NewSpanRecorder()
+	tp := sdktrace.NewTracerProvider(sdktrace.WithSpanProcessor(sr))
+	prev := otel.GetTracerProvider()
+	otel.SetTracerProvider(tp)
+	t.Cleanup(func() { otel.SetTracerProvider(prev) })
+	return sr
+}
+
+func rootSpanAttrs(t *testing.T, sr *tracetest.SpanRecorder, fn func(ctx context.Context)) map[attribute.Key]attribute.Value {
+	t.Helper()
+	ctx, root := otel.Tracer("test").Start(context.Background(), "root")
+	fn(ctx)
+	root.End()
+	for _, s := range sr.Ended() {
+		if s.Name() == "root" {
+			m := make(map[attribute.Key]attribute.Value, len(s.Attributes()))
+			for _, kv := range s.Attributes() {
+				m[kv.Key] = kv.Value
+			}
+			return m
+		}
+	}
+	t.Fatal("root span not recorded")
+	return nil
+}
+
+func assertSpanStr(t *testing.T, attrs map[attribute.Key]attribute.Value, key attribute.Key, want string) {
+	t.Helper()
+	v, ok := attrs[key]
+	if !ok {
+		t.Errorf("missing %s", key)
+		return
+	}
+	if v.AsString() != want {
+		t.Errorf("%s = %q, want %q", key, v.AsString(), want)
+	}
+}
+
+func TestCreateActor_StampsFullSpanIdentity(t *testing.T) {
+	ns := namespaceForTest("ns-span-create")
+	tc := setupTest(t, ns)
+	defer tc.cleanup()
+	createTemplate(t, tc, ns)
+
+	sr := installSpanRecorder(t)
+	attrs := rootSpanAttrs(t, sr, func(ctx context.Context) {
+		if _, err := tc.service.CreateActor(ctx, &ateapipb.CreateActorRequest{
+			ActorRef:               &ateapipb.ActorRef{Atespace: testAtespace, Name: "id1"},
+			ActorTemplateNamespace: ns,
+			ActorTemplateName:      "tmpl1",
+		}); err != nil {
+			t.Fatalf("CreateActor: %v", err)
+		}
+	})
+
+	assertSpanStr(t, attrs, ateattr.AtespaceKey, testAtespace)
+	assertSpanStr(t, attrs, ateattr.ActorIDKey, "id1")
+	assertSpanStr(t, attrs, ateattr.ActorTemplateNameKey, "tmpl1")
+	assertSpanStr(t, attrs, ateattr.ActorTemplateNamespaceKey, ns)
+	if v, ok := attrs[ateattr.ActorVersionKey]; !ok || v.Type() != attribute.INT64 || v.AsInt64() != 1 {
+		t.Errorf("%s = %v, want int64 1", ateattr.ActorVersionKey, v.Emit())
+	}
+}
+
+func TestDeleteActor_StampsRefSpanIdentity(t *testing.T) {
+	ns := namespaceForTest("ns-span-delete")
+	tc := setupTest(t, ns)
+	defer tc.cleanup()
+	createTemplate(t, tc, ns)
+	if _, err := tc.service.CreateActor(context.Background(), &ateapipb.CreateActorRequest{
+		ActorRef:               &ateapipb.ActorRef{Atespace: testAtespace, Name: "id1"},
+		ActorTemplateNamespace: ns,
+		ActorTemplateName:      "tmpl1",
+	}); err != nil {
+		t.Fatalf("seed CreateActor: %v", err)
+	}
+
+	sr := installSpanRecorder(t)
+	attrs := rootSpanAttrs(t, sr, func(ctx context.Context) {
+		if _, err := tc.service.DeleteActor(ctx, &ateapipb.DeleteActorRequest{
+			ActorRef: &ateapipb.ActorRef{Atespace: testAtespace, Name: "id1"},
+		}); err != nil {
+			t.Fatalf("DeleteActor: %v", err)
+		}
+	})
+
+	assertSpanStr(t, attrs, ateattr.AtespaceKey, testAtespace)
+	assertSpanStr(t, attrs, ateattr.ActorIDKey, "id1")
+}
+
+// The early ref stamp must land on the span even when the operation fails, so a
+// failed resume is still attributable to who/where.
+func TestResumeActor_ErrorStillStampsRefSpanIdentity(t *testing.T) {
+	ns := namespaceForTest("ns-span-resume-err")
+	tc := setupTest(t, ns)
+	defer tc.cleanup()
+
+	sr := installSpanRecorder(t)
+	attrs := rootSpanAttrs(t, sr, func(ctx context.Context) {
+		if _, err := tc.service.ResumeActor(ctx, &ateapipb.ResumeActorRequest{
+			ActorRef: &ateapipb.ActorRef{Atespace: testAtespace, Name: "missing"},
+		}); err == nil {
+			t.Fatal("expected error resuming missing actor")
+		}
+	})
+
+	assertSpanStr(t, attrs, ateattr.AtespaceKey, testAtespace)
+	assertSpanStr(t, attrs, ateattr.ActorIDKey, "missing")
+}

cmd/ateapi/internal/controlapi/suspend_actor.go

@@ -30,6 +30,7 @@ func (s *Service) SuspendActor(ctx context.Context, req *ateapipb.SuspendActorRe
 	if err := validateSuspendActorRequest(req); err != nil {
 		return nil, err
 	}
+	setSpanActorRefIdentity(ctx, req.GetActorRef().GetAtespace(), req.GetActorRef().GetName())
 
 	actor, err := s.actorWorkflow.SuspendActor(ctx, req.GetActorRef().GetAtespace(), req.GetActorRef().GetName())
 	if err != nil {
@@ -42,6 +43,7 @@ func (s *Service) SuspendActor(ctx context.Context, req *ateapipb.SuspendActorRe
 		return nil, err
 	}
 
+	setSpanActorIdentity(ctx, actor)
 	return &ateapipb.SuspendActorResponse{Actor: actor}, nil
 }
 

internal/ateattr/ateattr.go

@@ -0,0 +1,54 @@
+// Copyright 2026 Google LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+// Package ateattr projects an Actor onto substrate's ate.* identity attributes.
+// Identity is a span-level subject attribute (the producer is the substrate
+// component, the actor is the subject), so it belongs on spans rather than the
+// resource, and uses substrate's own ate.* namespace rather than service.*.
+package ateattr
+
+import (
+	"go.opentelemetry.io/otel/attribute"
+
+	"github.com/agent-substrate/substrate/pkg/proto/ateapipb"
+)
+
+// Dotted ate.* matches the metric-instrument naming (atenet.*, atelet.*), not the
+// ate.dev/ slash form used for k8s labels and stdout log fields.
+const (
+	AtespaceKey               = attribute.Key("ate.atespace")
+	ActorIDKey                = attribute.Key("ate.actor.id")
+	ActorTemplateNameKey      = attribute.Key("ate.actor.template.name")
+	ActorTemplateNamespaceKey = attribute.Key("ate.actor.template.namespace")
+	ActorVersionKey           = attribute.Key("ate.actor.version")
+)
+
+// ActorRefIdentity returns the subset knowable before the Actor record resolves.
+func ActorRefIdentity(atespace, actorID string) []attribute.KeyValue {
+	return []attribute.KeyValue{
+		AtespaceKey.String(atespace),
+		ActorIDKey.String(actorID),
+	}
+}
+
+// ActorIdentity is nil-safe; a nil Actor yields zero-valued attributes.
+func ActorIdentity(a *ateapipb.Actor) []attribute.KeyValue {
+	return []attribute.KeyValue{
+		AtespaceKey.String(a.GetMetadata().GetAtespace()),
+		ActorIDKey.String(a.GetMetadata().GetName()),
+		ActorTemplateNameKey.String(a.GetActorTemplateName()),
+		ActorTemplateNamespaceKey.String(a.GetActorTemplateNamespace()),
+		ActorVersionKey.Int64(a.GetMetadata().GetVersion()),
+	}
+}