Fix OTEL service.name consistency and dump-safe attrs

Resolve serviceName as env > settings > attrs["service.name"] > default,
then always write resourceAttributes["service.name"] so the two never
diverge. Redact high-risk resource attr values in otelConfigForDump.
Document Phoenix cloud as a base OTLP URL (exporter appends /v1/traces).

Author: TheGreatAxios

docs/PERFTRACE.md

@@ -57,7 +57,10 @@ Precedence:
 - **endpoint:** env overrides settings
 - **headers:** when `OTEL_EXPORTER_OTLP_HEADERS` is set, it fully replaces
   settings headers (prefer env so secrets stay out of the settings file)
-- **serviceName:** env > settings > `corbits-code`
+- **serviceName:** env `OTEL_SERVICE_NAME` > settings `serviceName` >
+  `resourceAttributes["service.name"]` > `corbits-code`. After merge,
+  `resourceAttributes["service.name"]` is always set to the resolved name so
+  the two never diverge.
 - **resourceAttributes:** settings merged with env; env wins on key conflict
 - **`otel.enabled: false`:** disables export when only settings provide an
   endpoint; an explicit env endpoint still enables export
@@ -82,6 +85,10 @@ No endpoint and no half-config → export stays disabled (not an error).
 - Header **values** are secrets. Prefer env for them.
 - `otelConfigForDump()` exposes only: enabled flag, endpoint, service name,
   resource attributes, and header **names** — never values.
+- Resource attribute values whose keys match `/secret|token|key|password|auth/i`
+  are replaced with `[redacted]` in the dump view (live export config is
+  unchanged). Prefer non-secret labels in `resourceAttributes`; put auth in
+  headers/env.
 - Local privacy-strict dump writers must call `otelConfigForDump` (or omit OTEL
   config entirely). Never serialize `OtelExportConfig.headers` into session
   artifacts, logs, or crash dumps.
@@ -104,7 +111,8 @@ Cloud / authenticated Phoenix: set the project endpoint and pass the API key as
 a header (exact header name follows Phoenix’s current docs):
 
 ```bash
-export OTEL_EXPORTER_OTLP_ENDPOINT="https://app.phoenix.arize.com/v1/traces"
+# Base URL only — the exporter appends /v1/traces (do not include the path here).
+export OTEL_EXPORTER_OTLP_ENDPOINT="https://app.phoenix.arize.com"
 export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer%20<phoenix-api-key>"
 export OTEL_SERVICE_NAME="corbits-code"
 ```

src/perf/otel-config.test.ts

@@ -121,7 +121,7 @@ describe("resolveOtelExportConfig", () => {
     }
   });
 
-  test("service name: env > settings > default", () => {
+  test("service name: env > settings > attrs > default", () => {
     const fromSettings = resolveOtelExportConfig(
       baseSettings({ endpoint: "https://c.example", serviceName: "from-settings" }),
       {},
@@ -137,6 +137,65 @@ describe("resolveOtelExportConfig", () => {
     expect(fromEnv.ok && fromEnv.config.enabled && fromEnv.config.serviceName).toBe("from-env");
   });
 
+  test("service.name: attrs used when env and settings serviceName unset", () => {
+    const result = resolveOtelExportConfig(
+      baseSettings({
+        endpoint: "https://c.example",
+        resourceAttributes: { "service.name": "from-attrs" },
+      }),
+      {},
+    );
+    expect(result.ok).toBe(true);
+    if (result.ok && result.config.enabled) {
+      expect(result.config.serviceName).toBe("from-attrs");
+      expect(result.config.resourceAttributes["service.name"]).toBe("from-attrs");
+    }
+  });
+
+  test("service.name: env wins over settings and attrs, always synced to attrs", () => {
+    const result = resolveOtelExportConfig(
+      baseSettings({
+        endpoint: "https://c.example",
+        serviceName: "from-settings",
+        resourceAttributes: { "service.name": "from-attrs" },
+      }),
+      { [OTEL_ENV.serviceName]: "from-env" },
+    );
+    expect(result.ok).toBe(true);
+    if (result.ok && result.config.enabled) {
+      expect(result.config.serviceName).toBe("from-env");
+      expect(result.config.resourceAttributes["service.name"]).toBe("from-env");
+    }
+  });
+
+  test("service.name: settings wins over attrs, always synced to attrs", () => {
+    const result = resolveOtelExportConfig(
+      baseSettings({
+        endpoint: "https://c.example",
+        serviceName: "from-settings",
+        resourceAttributes: { "service.name": "from-attrs" },
+      }),
+      {},
+    );
+    expect(result.ok).toBe(true);
+    if (result.ok && result.config.enabled) {
+      expect(result.config.serviceName).toBe("from-settings");
+      expect(result.config.resourceAttributes["service.name"]).toBe("from-settings");
+    }
+  });
+
+  test("service.name: env OTEL_RESOURCE_ATTRIBUTES service.name used when no env/settings name", () => {
+    const result = resolveOtelExportConfig(baseSettings({ endpoint: "https://c.example" }), {
+      [OTEL_ENV.resourceAttributes]: "service.name=from-env-attrs,team=corbits",
+    });
+    expect(result.ok).toBe(true);
+    if (result.ok && result.config.enabled) {
+      expect(result.config.serviceName).toBe("from-env-attrs");
+      expect(result.config.resourceAttributes["service.name"]).toBe("from-env-attrs");
+      expect(result.config.resourceAttributes.team).toBe("corbits");
+    }
+  });
+
   test("resource attributes merge with env winning on conflict", () => {
     const result = resolveOtelExportConfig(
       baseSettings({
@@ -290,4 +349,38 @@ describe("otelConfigForDump", () => {
   test("disabled dump view is empty of secrets", () => {
     expect(otelConfigForDump({ enabled: false })).toEqual({ enabled: false });
   });
+
+  test("redacts high-risk resource attribute values in dump view", () => {
+    const resolved = resolveOtelExportConfig(
+      baseSettings({
+        endpoint: "https://collector.example",
+        resourceAttributes: {
+          "deployment.environment": "prod",
+          "api_key": "should-not-leak",
+          "auth.token": "tok-secret",
+          "db.password": "p@ss",
+          team: "corbits",
+        },
+      }),
+      {},
+    );
+    expect(resolved.ok).toBe(true);
+    if (!resolved.ok || !resolved.config.enabled) throw new Error("expected enabled config");
+
+    // Live export config keeps raw values for the exporter.
+    expect(resolved.config.resourceAttributes.api_key).toBe("should-not-leak");
+
+    const dump = otelConfigForDump(resolved.config);
+    expect(dump.enabled).toBe(true);
+    if (!dump.enabled) throw new Error("expected enabled dump");
+    expect(dump.resourceAttributes["deployment.environment"]).toBe("prod");
+    expect(dump.resourceAttributes.team).toBe("corbits");
+    expect(dump.resourceAttributes.api_key).toBe("[redacted]");
+    expect(dump.resourceAttributes["auth.token"]).toBe("[redacted]");
+    expect(dump.resourceAttributes["db.password"]).toBe("[redacted]");
+    const serialized = JSON.stringify(dump);
+    expect(serialized).not.toContain("should-not-leak");
+    expect(serialized).not.toContain("tok-secret");
+    expect(serialized).not.toContain("p@ss");
+  });
 });

src/perf/otel-config.ts

@@ -205,8 +205,11 @@ function validateStringMap(
  * Precedence:
  * - endpoint: env > settings
  * - headers: env list fully replaces settings when env is set; else settings
- * - serviceName: env > settings > default
- * - resourceAttributes: settings then env (env wins on key conflict)
+ * - serviceName: env OTEL_SERVICE_NAME > settings.serviceName >
+ *   resourceAttributes["service.name"] > default
+ * - resourceAttributes: settings then env (env wins on key conflict); after
+ *   merge, resourceAttributes["service.name"] is always set to the resolved
+ *   serviceName so the two never diverge
  *
  * No endpoint → disabled (ok). Invalid partial/malformed config → not ok.
  */
@@ -289,12 +292,17 @@ export function resolveOtelExportConfig(
     resourceAttributes = { ...resourceAttributes, ...parsed.value };
   }
 
+  // serviceName: env > settings > attrs["service.name"] > default, then always
+  // write resourceAttributes["service.name"] so config.serviceName and attrs stay consistent.
+  const attrServiceName = trimOrEmpty(resourceAttributes["service.name"]);
   const serviceName =
     envServiceNameRaw.length > 0
       ? envServiceNameRaw
       : isNonEmptyString(otel?.serviceName)
         ? otel.serviceName.trim()
-        : DEFAULT_OTEL_SERVICE_NAME;
+        : attrServiceName.length > 0
+          ? attrServiceName
+          : DEFAULT_OTEL_SERVICE_NAME;
 
   if (serviceName.length === 0) {
     return {
@@ -304,10 +312,7 @@ export function resolveOtelExportConfig(
     };
   }
 
-  // Ensure service.name is present in resource attributes (OTEL resource convention).
-  if (resourceAttributes["service.name"] === undefined) {
-    resourceAttributes["service.name"] = serviceName;
-  }
+  resourceAttributes["service.name"] = serviceName;
 
   return {
     ok: true,
@@ -336,17 +341,37 @@ export function requireOtelExportConfig(
   return result.config;
 }
 
+/** Attr keys that look secret-bearing — values redacted in dump views only. */
+const SENSITIVE_ATTR_KEY = /secret|token|key|password|auth/i;
+
+/**
+ * Redact high-risk resource attribute values for dump/log views.
+ * Keys matching /secret|token|key|password|auth/i get a fixed placeholder.
+ * Does not mutate the live export config.
+ */
+export function redactResourceAttributesForDump(
+  attrs: Readonly<Record<string, string>>,
+): Readonly<Record<string, string>> {
+  const out: Record<string, string> = {};
+  for (const [key, value] of Object.entries(attrs)) {
+    out[key] = SENSITIVE_ATTR_KEY.test(key) ? "[redacted]" : value;
+  }
+  return Object.freeze(out);
+}
+
 /**
  * Strip secrets for local dumps and logs.
  * Never pass EnabledOtelExportConfig.headers into dump writers — use this.
+ * Resource attribute values for high-risk keys are redacted; prefer non-secret
+ * labels in resourceAttributes (auth belongs in headers/env).
  */
 export function otelConfigForDump(config: OtelExportConfig): OtelExportConfigDumpView {
   if (!config.enabled) return { enabled: false };
   return {
     enabled: true,
     endpoint: config.endpoint,
     serviceName: config.serviceName,
-    resourceAttributes: config.resourceAttributes,
+    resourceAttributes: redactResourceAttributesForDump(config.resourceAttributes),
     headerNames: Object.freeze(Object.keys(config.headers).sort()),
   };
 }