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

cmd/ateapi/internal/controlapi/create_actor.go

@@ -33,11 +33,12 @@ func (s *Service) CreateActor(ctx context.Context, req *ateapipb.CreateActorRequ
 	if err := validateCreateActorRequest(req); err != nil {
 		return nil, err
 	}
-
 	in := req.GetActor()
 	templateNamespace := in.GetActorTemplateNamespace()
 	templateName := in.GetActorTemplateName()
 
+	setSpanActorRefIdentity(ctx, in.GetMetadata().GetAtespace(), in.GetMetadata().GetName())
+
 	_, err := s.actorTemplateLister.ActorTemplates(templateNamespace).Get(templateName)
 	if err != nil {
 		if k8serrors.IsNotFound(err) {
@@ -76,6 +77,7 @@ func (s *Service) CreateActor(ctx context.Context, req *ateapipb.CreateActorRequ
 		return nil, fmt.Errorf("while recording actor: %w", err)
 	}
 
+	setSpanActorIdentity(ctx, stored)
 	return stored, nil
 }
 

cmd/ateapi/internal/controlapi/create_actor_test.go

@@ -0,0 +1,55 @@
+// 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/attribute"
+
+	"github.com/agent-substrate/substrate/internal/ateattr"
+	"github.com/agent-substrate/substrate/pkg/proto/ateapipb"
+)
+
+// CreateActor is the only lifecycle op with the full identity (incl. version)
+// available in the request, so the whole ate.* set should land on its span.
+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{
+			Actor: &ateapipb.Actor{
+				Metadata:               &ateapipb.ResourceMetadata{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())
+	}
+}

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.GetActor().GetAtespace(), req.GetActor().GetName())
 
 	deleted, err := s.persistence.DeleteActor(ctx, req.GetActor().GetAtespace(), req.GetActor().GetName())
 	if err != nil {

cmd/ateapi/internal/controlapi/delete_actor_test.go

@@ -0,0 +1,53 @@
+// 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"
+
+	"github.com/agent-substrate/substrate/internal/ateattr"
+	"github.com/agent-substrate/substrate/pkg/proto/ateapipb"
+)
+
+// Delete addresses the actor by ref (atespace + id) and does not resolve the
+// template/version, so only the ref identity is stamped.
+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{
+		Actor: &ateapipb.Actor{
+			Metadata:               &ateapipb.ResourceMetadata{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{
+			Actor: &ateapipb.ObjectRef{Atespace: testAtespace, Name: "id1"},
+		}); err != nil {
+			t.Fatalf("DeleteActor: %v", err)
+		}
+	})
+
+	assertSpanStr(t, attrs, ateattr.AtespaceKey, testAtespace)
+	assertSpanStr(t, attrs, ateattr.ActorIDKey, "id1")
+}

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.GetActor().GetAtespace(), req.GetActor().GetName())
 
 	actor, err := s.actorWorkflow.PauseActor(ctx, req.GetActor().GetAtespace(), req.GetActor().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.GetActor().GetAtespace(), req.GetActor().GetName())
 
 	actor, err := s.actorWorkflow.ResumeActor(ctx, req.GetActor().GetAtespace(), req.GetActor().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/resume_actor_test.go

@@ -0,0 +1,43 @@
+// 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"
+
+	"github.com/agent-substrate/substrate/internal/ateattr"
+	"github.com/agent-substrate/substrate/pkg/proto/ateapipb"
+)
+
+// The early ref stamp must land on the span even when the op 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{
+			Actor: &ateapipb.ObjectRef{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/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,119 @@
+// 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"
+)
+
+// installSpanRecorder swaps in a recording global TracerProvider. Span-producing
+// code fetches its tracer from the global provider at call time, so this must not
+// run in parallel; the prior provider is restored on cleanup. Shared by the
+// per-method span tests (create/delete/resume_actor_test.go).
+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
+}
+
+// rootSpanAttrs runs fn under a fresh recording root span and returns that span's
+// attributes, so a test can observe what the code under test stamps on the span
+// carried in ctx.
+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 TestSetSpanActorIdentity(t *testing.T) {
+	sr := installSpanRecorder(t)
+	actor := &ateapipb.Actor{
+		Metadata:               &ateapipb.ResourceMetadata{Atespace: "team-a", Name: "a1", Version: 3},
+		ActorTemplateNamespace: "ns1",
+		ActorTemplateName:      "tmpl1",
+	}
+
+	attrs := rootSpanAttrs(t, sr, func(ctx context.Context) {
+		setSpanActorIdentity(ctx, actor)
+	})
+
+	assertSpanStr(t, attrs, ateattr.AtespaceKey, "team-a")
+	assertSpanStr(t, attrs, ateattr.ActorIDKey, "a1")
+	assertSpanStr(t, attrs, ateattr.ActorTemplateNameKey, "tmpl1")
+	assertSpanStr(t, attrs, ateattr.ActorTemplateNamespaceKey, "ns1")
+	if v, ok := attrs[ateattr.ActorVersionKey]; !ok || v.Type() != attribute.INT64 || v.AsInt64() != 3 {
+		t.Errorf("%s = %v, want int64 3", ateattr.ActorVersionKey, v.Emit())
+	}
+}
+
+func TestSetSpanActorRefIdentity(t *testing.T) {
+	sr := installSpanRecorder(t)
+
+	attrs := rootSpanAttrs(t, sr, func(ctx context.Context) {
+		setSpanActorRefIdentity(ctx, "team-a", "a1")
+	})
+
+	assertSpanStr(t, attrs, ateattr.AtespaceKey, "team-a")
+	assertSpanStr(t, attrs, ateattr.ActorIDKey, "a1")
+	// The ref-only stamp must not invent template/version (not known pre-resolve).
+	for _, k := range []attribute.Key{ateattr.ActorTemplateNameKey, ateattr.ActorTemplateNamespaceKey, ateattr.ActorVersionKey} {
+		if _, ok := attrs[k]; ok {
+			t.Errorf("unexpected %s on ref-only stamp", k)
+		}
+	}
+}
+
+// A context with no recording span must be a safe no-op, so call sites need no guard.
+func TestSetSpanActorIdentity_NoRecordingSpanIsNoop(t *testing.T) {
+	setSpanActorIdentity(context.Background(), &ateapipb.Actor{Metadata: &ateapipb.ResourceMetadata{Name: "a1"}})
+	setSpanActorRefIdentity(context.Background(), "team-a", "a1")
+}

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.GetActor().GetAtespace(), req.GetActor().GetName())
 
 	actor, err := s.actorWorkflow.SuspendActor(ctx, req.GetActor().GetAtespace(), req.GetActor().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
 }