@oneuptime/common 12.0.34 → 13.0.1

package/Tests/Server/Utils/Telemetry/ContextSpanProcessor.test.ts

@@ -0,0 +1,281 @@
+import { afterEach, describe, expect, jest, test } from "@jest/globals";
+import type { Context } from "@opentelemetry/api";
+import type { ReadableSpan, Span } from "@opentelemetry/sdk-trace-base";
+import ContextSpanProcessor from "../../../../Server/Utils/Telemetry/ContextSpanProcessor";
+import TelemetryContext from "../../../../Server/Utils/Telemetry/TelemetryContext";
+
+/*
+ * This processor runs on the creation of EVERY span in every OneUptime
+ * process. That is what makes it useful - it is how projectId and userId
+ * reach the ~1958 attribute-less @CaptureSpan spans without touching any of
+ * those call sites - and it is also what makes it dangerous.
+ *
+ * Two properties follow.
+ *
+ *   IT MUST NEVER THROW. onStart sits inside the OpenTelemetry SDK's tracer,
+ *   on the hot path of every traced operation in the product. An exception
+ *   escaping it does not lose a span, it fails the OPERATION the span was
+ *   describing - telemetry taking down the thing it was watching. The
+ *   swallow-everything catch is the point of the file, so the tests drive it
+ *   with a context that throws and a span that throws.
+ *
+ *   IT MUST NOT WRITE undefined. A context attribute that is absent has to
+ *   stay absent rather than being stamped as a literal `undefined`, which is
+ *   both a wasted attribute slot on every span and a value that reads, on a
+ *   dashboard, as though the identifier were known to be empty.
+ */
+
+interface RecordedAttribute {
+  key: string;
+  value: unknown;
+}
+
+interface FakeSpan {
+  attributes: Array<RecordedAttribute>;
+}
+
+type BuildSpanFunction = (options?: { throwOnSet?: boolean }) => {
+  span: Span;
+  recorded: Array<RecordedAttribute>;
+};
+
+const buildSpan: BuildSpanFunction = (options?: {
+  throwOnSet?: boolean;
+}): { span: Span; recorded: Array<RecordedAttribute> } => {
+  const recorded: Array<RecordedAttribute> = [];
+
+  const span: FakeSpan & {
+    setAttribute: (key: string, value: unknown) => void;
+  } = {
+    attributes: recorded,
+    setAttribute: (key: string, value: unknown): void => {
+      if (options?.throwOnSet) {
+        throw new Error("span is already ended");
+      }
+      recorded.push({ key: key, value: value });
+    },
+  };
+
+  return { span: span as unknown as Span, recorded: recorded };
+};
+
+const EMPTY_CONTEXT: Context = {} as Context;
+
+type StartInContextFunction = (
+  attributes: Record<string, string | number | boolean>,
+  options?: { throwOnSet?: boolean },
+) => Array<RecordedAttribute>;
+
+const startInContext: StartInContextFunction = (
+  attributes: Record<string, string | number | boolean>,
+  options?: { throwOnSet?: boolean },
+): Array<RecordedAttribute> => {
+  const built: { span: Span; recorded: Array<RecordedAttribute> } =
+    buildSpan(options);
+
+  TelemetryContext.runWithContext(attributes, (): void => {
+    new ContextSpanProcessor().onStart(built.span, EMPTY_CONTEXT);
+  });
+
+  return built.recorded;
+};
+
+describe("the ambient context is stamped onto every span", () => {
+  afterEach(() => {
+    jest.restoreAllMocks();
+  });
+
+  test("copies the tenant identifiers of the enclosing scope", () => {
+    const recorded: Array<RecordedAttribute> = startInContext({
+      projectId: "project-1",
+      userId: "user-1",
+    });
+
+    expect(recorded).toEqual(
+      expect.arrayContaining([
+        { key: "projectId", value: "project-1" },
+        { key: "userId", value: "user-1" },
+      ]),
+    );
+  });
+
+  test("copies numbers and booleans without coercing them to strings", () => {
+    const recorded: Array<RecordedAttribute> = startInContext({
+      retryCount: 3,
+      isRetry: true,
+    });
+
+    expect(recorded).toEqual(
+      expect.arrayContaining([
+        { key: "retryCount", value: 3 },
+        { key: "isRetry", value: true },
+      ]),
+    );
+  });
+
+  /*
+   * Zero and false are real values. A truthiness check instead of an
+   * undefined check would silently drop exactly the attributes an operator
+   * most wants to filter on - "the runs where retryCount is 0".
+   */
+  test("copies zero and false, which a truthiness check would have dropped", () => {
+    const recorded: Array<RecordedAttribute> = startInContext({
+      retryCount: 0,
+      isRetry: false,
+      emptyLabel: "",
+    });
+
+    expect(recorded).toEqual(
+      expect.arrayContaining([
+        { key: "retryCount", value: 0 },
+        { key: "isRetry", value: false },
+        { key: "emptyLabel", value: "" },
+      ]),
+    );
+  });
+
+  test("writes nothing at all when there is no ambient scope", () => {
+    const built: { span: Span; recorded: Array<RecordedAttribute> } =
+      buildSpan();
+
+    new ContextSpanProcessor().onStart(built.span, EMPTY_CONTEXT);
+
+    expect(built.recorded).toEqual([]);
+  });
+
+  test("writes nothing when the scope is empty", () => {
+    expect(startInContext({})).toEqual([]);
+  });
+
+  /*
+   * An absent identifier must stay absent. Stamping a literal `undefined`
+   * wastes an attribute slot on every span and, on a dashboard, reads as
+   * though the identifier were known to be empty.
+   */
+  test("never stamps an undefined value", () => {
+    const built: { span: Span; recorded: Array<RecordedAttribute> } =
+      buildSpan();
+
+    jest.spyOn(TelemetryContext, "getAttributes").mockReturnValue({
+      projectId: "project-1",
+      monitorId: undefined,
+      incidentId: null,
+    } as unknown as Record<string, string | number | boolean>);
+
+    new ContextSpanProcessor().onStart(built.span, EMPTY_CONTEXT);
+
+    expect(
+      built.recorded.map((attribute: RecordedAttribute) => {
+        return attribute.key;
+      }),
+    ).toEqual(["projectId"]);
+  });
+
+  test("a nested scope stamps the identifiers of both levels", () => {
+    const built: { span: Span; recorded: Array<RecordedAttribute> } =
+      buildSpan();
+
+    TelemetryContext.runWithContext({ projectId: "project-1" }, (): void => {
+      TelemetryContext.runWithContext({ monitorId: "monitor-1" }, (): void => {
+        new ContextSpanProcessor().onStart(built.span, EMPTY_CONTEXT);
+      });
+    });
+
+    expect(built.recorded).toEqual(
+      expect.arrayContaining([
+        { key: "projectId", value: "project-1" },
+        { key: "monitorId", value: "monitor-1" },
+      ]),
+    );
+  });
+
+  test("the scope does not leak out of the run it was seeded for", () => {
+    TelemetryContext.runWithContext({ projectId: "project-1" }, (): void => {
+      // seeded and immediately left
+    });
+
+    const built: { span: Span; recorded: Array<RecordedAttribute> } =
+      buildSpan();
+
+    new ContextSpanProcessor().onStart(built.span, EMPTY_CONTEXT);
+
+    expect(built.recorded).toEqual([]);
+  });
+});
+
+describe("telemetry never takes down the operation it is watching", () => {
+  afterEach(() => {
+    jest.restoreAllMocks();
+  });
+
+  /*
+   * onStart runs inside the SDK's tracer, on the hot path of every traced
+   * operation. An exception escaping it does not lose a span - it fails the
+   * work the span was describing.
+   */
+  test("swallows a span that refuses attributes", () => {
+    expect(() => {
+      return startInContext({ projectId: "project-1" }, { throwOnSet: true });
+    }).not.toThrow();
+  });
+
+  test("swallows a context that throws while being read", () => {
+    jest.spyOn(TelemetryContext, "getAttributes").mockImplementation(() => {
+      throw new Error("async local storage is unhappy");
+    });
+
+    const built: { span: Span; recorded: Array<RecordedAttribute> } =
+      buildSpan();
+
+    expect(() => {
+      return new ContextSpanProcessor().onStart(built.span, EMPTY_CONTEXT);
+    }).not.toThrow();
+  });
+
+  test("swallows a context that is not an object at all", () => {
+    jest
+      .spyOn(TelemetryContext, "getAttributes")
+      .mockReturnValue(null as unknown as Record<string, string>);
+
+    const built: { span: Span; recorded: Array<RecordedAttribute> } =
+      buildSpan();
+
+    expect(() => {
+      return new ContextSpanProcessor().onStart(built.span, EMPTY_CONTEXT);
+    }).not.toThrow();
+  });
+});
+
+describe("the rest of the SpanProcessor contract", () => {
+  /*
+   * Enrichment happens entirely at creation, so onEnd is deliberately inert.
+   * Doing anything to an ended span here would be both useless and a way to
+   * throw on the export path.
+   */
+  test("onEnd does nothing and does not throw", () => {
+    expect(() => {
+      return new ContextSpanProcessor().onEnd({} as ReadableSpan);
+    }).not.toThrow();
+  });
+
+  test("shutdown resolves, so the SDK's teardown is never blocked", async () => {
+    await expect(
+      new ContextSpanProcessor().shutdown(),
+    ).resolves.toBeUndefined();
+  });
+
+  test("forceFlush resolves, so a flush before exit never hangs", async () => {
+    await expect(
+      new ContextSpanProcessor().forceFlush(),
+    ).resolves.toBeUndefined();
+  });
+
+  test("shutdown and forceFlush stay resolvable after an enrichment failure", async () => {
+    const processor: ContextSpanProcessor = new ContextSpanProcessor();
+
+    processor.onStart(buildSpan({ throwOnSet: true }).span, EMPTY_CONTEXT);
+
+    await expect(processor.forceFlush()).resolves.toBeUndefined();
+    await expect(processor.shutdown()).resolves.toBeUndefined();
+  });
+});

package/Tests/Server/Utils/Telemetry/InventoryDuplicateIdentity.test.ts

@@ -0,0 +1,316 @@
+import InventoryItem, {
+  EntityAttributes,
+  ExtractedEntity,
+  ResourceEntityRef,
+} from "../../../../Server/Utils/Telemetry/TelemetryEntity";
+import EntityType from "../../../../Types/Telemetry/EntityType";
+import { describe, expect, test } from "@jest/globals";
+
+/*
+ * Regression suite for duplicate Inventory items.
+ *
+ * `InventoryItem` has a unique index on (projectId, entityType, entityKey),
+ * so two rows of the same type in one project can only mean one thing: the
+ * same real object hashed to two different keys. Nothing downstream can undo
+ * that — the two rows are, as far as the registry is concerned, two things —
+ * and because both keep being observed, neither ever ages out. The Inventory
+ * list then shows a node, pod or service twice, both marked Discovered, both
+ * with the same name, because the display name is derived from the attributes
+ * the two identities SHARE rather than the ones that differ.
+ *
+ * The rule these tests exist to hold: an entity's identity must depend only on
+ * WHICH OBJECT is being described, never on WHICH PIPELINE is describing it.
+ * Every case below is a pair of resources that our own shipped configuration
+ * produces for one object, differing only in what the producing collector was
+ * able to resolve.
+ */
+
+const PROJECT: string = "proj-dup-1";
+
+function entitiesFor(
+  attrs: EntityAttributes,
+  entityRefs?: Array<ResourceEntityRef>,
+): Array<ExtractedEntity> {
+  return InventoryItem.extractEntities({
+    projectId: PROJECT,
+    attributes: attrs,
+    ...(entityRefs ? { entityRefs } : {}),
+  });
+}
+
+function entityOfType(
+  attrs: EntityAttributes,
+  type: EntityType,
+): ExtractedEntity | undefined {
+  return entitiesFor(attrs).find((e: ExtractedEntity) => {
+    return e.entityType === type;
+  });
+}
+
+function keyOfType(attrs: EntityAttributes, type: EntityType): string {
+  const entity: ExtractedEntity | undefined = entityOfType(attrs, type);
+  expect(entity).toBeDefined();
+  return entity!.entityKey;
+}
+
+const CLUSTER: string = "prod-us";
+
+/*
+ * The two collectors the `kubernetes-agent` chart installs, reduced to the
+ * resource attributes each actually carries for the SAME node.
+ *
+ * Deployment / metrics-collector: the `k8s_cluster` receiver reports node
+ * metrics (`k8s.node.condition_ready`, allocatable cpu/memory/storage) and
+ * resolves node uids from the Kubernetes API.
+ *
+ * DaemonSet / node-collector: kubeletstats, hostmetrics, the cAdvisor scrape
+ * and the pod filelog receiver. None of them can produce a node uid — the
+ * kubelet summary API has no such field and `k8sattributes` is not asked to
+ * extract one — so the chart stamps `k8s.node.name` from the downward API
+ * instead.
+ */
+const NODE_FROM_K8S_CLUSTER_RECEIVER: EntityAttributes = {
+  "k8s.cluster.name": CLUSTER,
+  "k8s.node.name": "ip-10-0-1-23.ec2.internal",
+  "k8s.node.uid": "a8170da5-c826-49b0-b48b-a35af366e689",
+  "service.name": `kubernetes-agent-${CLUSTER}`,
+};
+
+const NODE_FROM_DAEMONSET: EntityAttributes = {
+  "k8s.cluster.name": CLUSTER,
+  "k8s.node.name": "ip-10-0-1-23.ec2.internal",
+  "service.name": `kubernetes-agent-${CLUSTER}`,
+};
+
+/*
+ * The same pod as seen by the deployment collector (k8sattributes resolves
+ * `k8s.pod.uid`) and by a pod-log record that only carries the pod name.
+ */
+const POD_WITH_UID: EntityAttributes = {
+  "k8s.cluster.name": CLUSTER,
+  "k8s.namespace.name": "shop",
+  "k8s.pod.name": "checkout-api-7d9f884c7d-q5bz2",
+  "k8s.pod.uid": "7c2f9dd0-8400-4c47-9c54-321ebeb9543b",
+};
+
+const POD_WITHOUT_UID: EntityAttributes = {
+  "k8s.cluster.name": CLUSTER,
+  "k8s.namespace.name": "shop",
+  "k8s.pod.name": "checkout-api-7d9f884c7d-q5bz2",
+};
+
+describe("one object, one identity, whichever collector saw it", () => {
+  test("a node reported with a uid and the same node reported without one are one entity", () => {
+    expect(
+      keyOfType(NODE_FROM_K8S_CLUSTER_RECEIVER, EntityType.KubernetesNode),
+    ).toBe(keyOfType(NODE_FROM_DAEMONSET, EntityType.KubernetesNode));
+  });
+
+  test("a pod reported with a uid and the same pod reported without one are one entity", () => {
+    expect(keyOfType(POD_WITH_UID, EntityType.KubernetesPod)).toBe(
+      keyOfType(POD_WITHOUT_UID, EntityType.KubernetesPod),
+    );
+  });
+
+  test("node identity is the cluster plus the node name, and nothing else", () => {
+    expect(
+      entityOfType(NODE_FROM_K8S_CLUSTER_RECEIVER, EntityType.KubernetesNode)!
+        .identifyingAttributes,
+    ).toEqual({
+      "k8s.cluster.name": CLUSTER,
+      "k8s.node.name": "ip-10-0-1-23.ec2.internal",
+    });
+  });
+
+  test("pod identity is the cluster, namespace and pod name, and nothing else", () => {
+    expect(
+      entityOfType(POD_WITH_UID, EntityType.KubernetesPod)!
+        .identifyingAttributes,
+    ).toEqual({
+      "k8s.cluster.name": CLUSTER,
+      "k8s.namespace.name": "shop",
+      "k8s.pod.name": "checkout-api-7d9f884c7d-q5bz2",
+    });
+  });
+
+  test("the uid is still recorded, just not as identity", () => {
+    expect(
+      entityOfType(NODE_FROM_K8S_CLUSTER_RECEIVER, EntityType.KubernetesNode)!
+        .descriptiveAttributes,
+    ).toMatchObject({
+      "k8s.node.uid": "a8170da5-c826-49b0-b48b-a35af366e689",
+    });
+    expect(
+      entityOfType(POD_WITH_UID, EntityType.KubernetesPod)!
+        .descriptiveAttributes,
+    ).toMatchObject({
+      "k8s.pod.uid": "7c2f9dd0-8400-4c47-9c54-321ebeb9543b",
+    });
+  });
+
+  test("a pod that keeps its name across a restart keeps its inventory row", () => {
+    /*
+     * A StatefulSet pod is recreated under the same name with a fresh uid.
+     * Under uid identity that minted a new registry row per incarnation; the
+     * name is what an inventory is actually tracking.
+     */
+    const before: string = keyOfType(POD_WITH_UID, EntityType.KubernetesPod);
+    const after: string = keyOfType(
+      {
+        ...POD_WITH_UID,
+        "k8s.pod.uid": "0000aaaa-1111-2222-3333-444455556666",
+      },
+      EntityType.KubernetesPod,
+    );
+
+    expect(after).toBe(before);
+  });
+});
+
+describe("identity that genuinely differs must stay different", () => {
+  test("the same node name in two clusters is two entities", () => {
+    expect(keyOfType(NODE_FROM_DAEMONSET, EntityType.KubernetesNode)).not.toBe(
+      keyOfType(
+        { ...NODE_FROM_DAEMONSET, "k8s.cluster.name": "prod-eu" },
+        EntityType.KubernetesNode,
+      ),
+    );
+  });
+
+  test("the same pod name in two namespaces is two entities", () => {
+    expect(keyOfType(POD_WITHOUT_UID, EntityType.KubernetesPod)).not.toBe(
+      keyOfType(
+        { ...POD_WITHOUT_UID, "k8s.namespace.name": "checkout" },
+        EntityType.KubernetesPod,
+      ),
+    );
+  });
+
+  test("the same pod name in two clusters is two entities", () => {
+    expect(keyOfType(POD_WITHOUT_UID, EntityType.KubernetesPod)).not.toBe(
+      keyOfType(
+        { ...POD_WITHOUT_UID, "k8s.cluster.name": "prod-eu" },
+        EntityType.KubernetesPod,
+      ),
+    );
+  });
+
+  test("two different nodes in one cluster are two entities", () => {
+    expect(keyOfType(NODE_FROM_DAEMONSET, EntityType.KubernetesNode)).not.toBe(
+      keyOfType(
+        {
+          ...NODE_FROM_DAEMONSET,
+          "k8s.node.name": "ip-10-0-1-24.ec2.internal",
+        },
+        EntityType.KubernetesNode,
+      ),
+    );
+  });
+
+  test("a uid-only node and a named node are not silently merged", () => {
+    /*
+     * Nothing can prove these are the same object from the resource alone, so
+     * they stay distinct. The uid-only shape exists only for a producer that
+     * carries no name at all.
+     */
+    expect(
+      keyOfType(
+        { "k8s.cluster.name": CLUSTER, "k8s.node.uid": "node-uid-only" },
+        EntityType.KubernetesNode,
+      ),
+    ).not.toBe(keyOfType(NODE_FROM_DAEMONSET, EntityType.KubernetesNode));
+  });
+});
+
+describe("casing and whitespace do not fork identity", () => {
+  test.each([
+    ["upper-cased node name", { "k8s.node.name": "IP-10-0-1-23.EC2.INTERNAL" }],
+    ["padded node name", { "k8s.node.name": "  ip-10-0-1-23.ec2.internal  " }],
+    ["upper-cased cluster", { "k8s.cluster.name": "PROD-US" }],
+  ])(
+    "%s resolves to the same node entity",
+    (_label: string, override: EntityAttributes) => {
+      expect(
+        keyOfType(
+          { ...NODE_FROM_DAEMONSET, ...override },
+          EntityType.KubernetesNode,
+        ),
+      ).toBe(keyOfType(NODE_FROM_DAEMONSET, EntityType.KubernetesNode));
+    },
+  );
+});
+
+describe("one resource describes at most one entity per type", () => {
+  /*
+   * A resource is one pod, on one node, in one cluster. `entity_refs` are
+   * producer-supplied and nothing stops a producer sending two refs of the
+   * same type on one resource; promoting both put two Inventory rows in from
+   * a single batch. The extra ref stays a membership key so no signal loses
+   * its queryable identity.
+   */
+  const TWO_POD_REFS: Array<ResourceEntityRef> = [
+    { type: "k8s.pod", idKeys: ["k8s.pod.name"] },
+    { type: "k8s.pod", idKeys: ["k8s.pod.uid"] },
+  ];
+
+  test("only the first ref of a type is promoted to a registry row", () => {
+    const pods: Array<ExtractedEntity> = entitiesFor(
+      POD_WITH_UID,
+      TWO_POD_REFS,
+    ).filter((e: ExtractedEntity) => {
+      return e.entityType === EntityType.KubernetesPod;
+    });
+
+    expect(pods).toHaveLength(2);
+    expect(
+      pods.filter((p: ExtractedEntity) => {
+        return !p.membershipOnly;
+      }),
+    ).toHaveLength(1);
+  });
+
+  test("the demoted ref keeps its key so signals stay queryable by it", () => {
+    const pods: Array<ExtractedEntity> = entitiesFor(
+      POD_WITH_UID,
+      TWO_POD_REFS,
+    ).filter((e: ExtractedEntity) => {
+      return e.entityType === EntityType.KubernetesPod;
+    });
+
+    const keys: Array<string> = pods.map((p: ExtractedEntity) => {
+      return p.entityKey;
+    });
+
+    expect(new Set(keys).size).toBe(2);
+    expect(
+      InventoryItem.extractEntityKeys({
+        projectId: PROJECT,
+        attributes: POD_WITH_UID,
+        entityRefs: TWO_POD_REFS,
+      }),
+    ).toEqual(expect.arrayContaining(keys));
+  });
+
+  test("refs of different types are all promoted", () => {
+    const entities: Array<ExtractedEntity> = entitiesFor(POD_WITH_UID, [
+      { type: "k8s.pod", idKeys: ["k8s.pod.name"] },
+      { type: "k8s.namespace", idKeys: ["k8s.namespace.name"] },
+    ]);
+
+    expect(
+      entities.filter((e: ExtractedEntity) => {
+        return !e.membershipOnly;
+      }),
+    ).toHaveLength(2);
+  });
+
+  test("the heuristic resolvers already emit one entity per type", () => {
+    const types: Array<EntityType> = entitiesFor(POD_WITH_UID).map(
+      (e: ExtractedEntity) => {
+        return e.entityType;
+      },
+    );
+
+    expect(new Set(types).size).toBe(types.length);
+  });
+});