Improve clarity around versions and instances

Author: Ankcorn

datadog-dashboard.json

@@ -620,8 +620,8 @@
 			"default": "*"
 		},
 		{
-			"name": "deployment_id",
-			"prefix": "deployment_id",
+			"name": "instance_id",
+			"prefix": "instance_id",
 			"available_values": [],
 			"default": "*"
 		},

readme.md

@@ -90,9 +90,12 @@ Use `instances.total.max - instances.total.healthy` to calculate available capac
 | `bandwidth.rx` | count | bytes | Bytes received |
 | `bandwidth.tx` | count | bytes | Bytes transmitted |
 
-**Tags:** `account_id`, `application_id`, `application_name`, `deployment_id`, `placement_id`, `stat`
+**Tags:** `account_id`, `application_id`, `application_name`, `version`, `instance_id`, `placement_id`, `stat`
 
-The `stat` tag indicates the aggregation: `p50`, `p90`, `p99`, `max` (bandwidth metrics don't have a stat tag).
+- `version` - The container application version number
+- `instance_id` - The instance identifier (maps to Cloudflare's deploymentId)
+- `placement_id` - The placement identifier (specific realization of an instance, useful for tracking restarts/churn)
+- `stat` - The aggregation type: `p50`, `p90`, `p99`, `max` (bandwidth metrics don't have a stat tag)
 
 ## Datadog Dashboard
 

src/api/cloudflare.ts

@@ -23,10 +23,10 @@ export interface GraphQLResponse<T> {
 }
 
 const CONTAINERS_METRICS_QUERY = `
-query GetCloudchamberMetrics($accountTag: string!, $datetimeStart: Time, $datetimeEnd: Time, $applicationIds: [string!]) {
+query GetCloudchamberMetrics($accountTag: string!, $datetimeStart: Time, $datetimeEnd: Time, $applicationId: string!) {
   viewer {
     accounts(filter: {accountTag: $accountTag}) {
-      cloudchamberMetricsAdaptiveGroups(limit: 10000, filter: {applicationId_in: $applicationIds, datetimeMinute_geq: $datetimeStart, datetimeMinute_leq: $datetimeEnd}) {
+      cloudchamberMetricsAdaptiveGroups(limit: 10000, filter: {applicationId: $applicationId, datetimeMinute_geq: $datetimeStart, datetimeMinute_leq: $datetimeEnd}) {
         max {
           memory
           cpuLoad
@@ -50,8 +50,8 @@ query GetCloudchamberMetrics($accountTag: string!, $datetimeStart: Time, $dateti
         dimensions {
           datetimeMinute
           applicationId
-          placementId
           deploymentId
+          placementId
         }
       }
     }
@@ -98,13 +98,13 @@ export class CloudflareApi {
 	}
 
 	/**
-	 * Get metrics for multiple container applications
-	 * @param applicationIds - Array of container application IDs
+	 * Get metrics for a container application
+	 * @param applicationId - Container application ID
 	 * @param startTime - Start of the time range (defaults to 5 minutes ago)
 	 * @param endTime - End of the time range (defaults to now)
 	 */
 	async getContainerMetrics(
-		applicationIds: string[],
+		applicationId: string,
 		startTime?: Date,
 		endTime?: Date,
 	): Promise<MetricsGroup[]> {
@@ -115,7 +115,7 @@ export class CloudflareApi {
 			accountTag: this.config.accountId,
 			datetimeStart: start.toISOString(),
 			datetimeEnd: now.toISOString(),
-			applicationIds,
+			applicationId,
 		};
 
 		const response = await fetch(this.graphqlUrl, {
@@ -143,7 +143,7 @@ export class CloudflareApi {
 			data.data?.viewer?.accounts?.[0]?.cloudchamberMetricsAdaptiveGroups ?? [];
 
 		console.log("Fetched container metrics", {
-			applicationCount: applicationIds.length,
+			applicationId,
 			groupCount: groups.length,
 		});
 

src/metrics.ts

@@ -9,6 +9,7 @@ export interface ContainerWithMetrics {
 export interface ContainerInfo {
 	id: string;
 	name: string;
+	version: number;
 }
 
 /**
@@ -28,7 +29,8 @@ export function formatMetricsForContainer(
 			`account_id:${accountId}`,
 			`application_id:${group.dimensions.applicationId}`,
 			`application_name:${container.name}`,
-			`deployment_id:${group.dimensions.deploymentId}`,
+			`version:${container.version}`,
+			`instance_id:${group.dimensions.deploymentId}`,
 			`placement_id:${group.dimensions.placementId}`,
 		];
 

src/types.ts

@@ -21,6 +21,7 @@ export type Container = z.infer<typeof Container>;
 export const Container = z.looseObject({
 	id: z.string(),
 	name: z.string(),
+	version: z.number(),
 	instances: z.number().optional(),
 	max_instances: z.number().optional(),
 	health: HealthSchema.optional(),

src/workflow.ts

@@ -66,19 +66,23 @@ export class MetricsExporterWorkflow extends WorkflowEntrypoint<Env> {
 				);
 				await datadog.sendMetrics(healthMetrics);
 
-				return result.map((c) => ({ id: c.id, name: c.name }));
+				return result.map((c) => ({
+					id: c.id,
+					name: c.name,
+					version: c.version,
+				}));
 			},
 		);
 
 		let totalMetrics = 0;
 
 		for (const container of containers) {
 			const count = await step.do(
-				`export metrics: ${container.name}`,
+				`Download Metrics: ${container.name}`,
 				STEP_CONFIG,
 				async () => {
 					const metricsGroups = await cloudflare.getContainerMetrics(
-						[container.id],
+						container.id,
 						start,
 						end,
 					);
@@ -95,7 +99,7 @@ export class MetricsExporterWorkflow extends WorkflowEntrypoint<Env> {
 						batches.map(
 							(batch, i) => () =>
 								step.do(
-									`send batch ${i + 1}/${batches.length} (${batch.length} metrics)`,
+									`Export Metrics: ${container.name} batch ${i + 1}/${batches.length}`,
 									STEP_CONFIG,
 									async () => {
 										await datadog.sendMetrics(batch);

test/metricsformatting.test.ts

@@ -16,7 +16,7 @@ const TEST_TIMESTAMP = 1733414400; // 2024-12-05T16:00:00Z
 
 describe("formatMetricsForContainer", () => {
 	it("formats metrics for a single container", () => {
-		const container = { id: "app-123", name: "my-app" };
+		const container = { id: "app-123", name: "my-app", version: 1 };
 		const metrics = formatMetricsForContainer(
 			TEST_ACCOUNT_ID,
 			container,
@@ -29,7 +29,7 @@ describe("formatMetricsForContainer", () => {
 	});
 
 	it("formats multiple metrics groups", () => {
-		const container = { id: "app-123", name: "my-app" };
+		const container = { id: "app-123", name: "my-app", version: 1 };
 		const metrics = formatMetricsForContainer(
 			TEST_ACCOUNT_ID,
 			container,
@@ -42,13 +42,13 @@ describe("formatMetricsForContainer", () => {
 	});
 
 	it("includes correct tags", () => {
-		const container = { id: "app-123", name: "my-app" };
+		const container = { id: "app-123", name: "my-app", version: 1 };
 		const group = createMockMetricsGroup({
 			dimensions: {
 				applicationId: "app-test",
 				datetimeMinute: "2025-12-05T16:00:00Z",
-				deploymentId: "deploy-test",
-				placementId: "place-test",
+				deploymentId: "instance-test",
+				placementId: "placement-test",
 			},
 		});
 
@@ -68,12 +68,13 @@ describe("formatMetricsForContainer", () => {
 		expect(cpuMetric?.tags).toContain(`account_id:${TEST_ACCOUNT_ID}`);
 		expect(cpuMetric?.tags).toContain("application_id:app-test");
 		expect(cpuMetric?.tags).toContain("application_name:my-app");
-		expect(cpuMetric?.tags).toContain("deployment_id:deploy-test");
-		expect(cpuMetric?.tags).toContain("placement_id:place-test");
+		expect(cpuMetric?.tags).toContain("version:1");
+		expect(cpuMetric?.tags).toContain("instance_id:instance-test");
+		expect(cpuMetric?.tags).toContain("placement_id:placement-test");
 	});
 
 	it("returns empty array for no metrics groups", () => {
-		const container = { id: "app-123", name: "my-app" };
+		const container = { id: "app-123", name: "my-app", version: 1 };
 		const metrics = formatMetricsForContainer(
 			TEST_ACCOUNT_ID,
 			container,
@@ -130,8 +131,8 @@ describe("formatContainerMetrics", () => {
 			dimensions: {
 				applicationId: "app-test",
 				datetimeMinute: "2025-12-05T16:00:00Z",
-				deploymentId: "deploy-test",
-				placementId: "place-test",
+				deploymentId: "instance-test",
+				placementId: "placement-test",
 			},
 		});
 
@@ -159,8 +160,8 @@ describe("formatContainerMetrics", () => {
 		expect(cpuMetric?.tags).toContain(
 			`application_name:${mockContainers[0].name}`,
 		);
-		expect(cpuMetric?.tags).toContain("deployment_id:deploy-test");
-		expect(cpuMetric?.tags).toContain("placement_id:place-test");
+		expect(cpuMetric?.tags).toContain("instance_id:instance-test");
+		expect(cpuMetric?.tags).toContain("placement_id:placement-test");
 		expect(cpuMetric?.tags).toContain("stat:p50");
 	});
 

test/mocks/data.ts

@@ -11,6 +11,7 @@ export const mockContainers: Container[] = [
 	{
 		id: "app-123-abc",
 		name: "my-web-app",
+		version: 3,
 		instances: 5,
 		max_instances: 10,
 		health: {
@@ -29,6 +30,7 @@ export const mockContainers: Container[] = [
 	{
 		id: "app-456-def",
 		name: "api-service",
+		version: 1,
 		instances: 3,
 		max_instances: 5,
 		health: {
@@ -74,8 +76,8 @@ export const mockMetricsGroups: MetricsGroup[] = [
 		dimensions: {
 			applicationId: "app-123-abc",
 			datetimeMinute: "2025-12-05T16:00:00Z",
-			deploymentId: "deploy-001",
-			placementId: "place-us-east-1",
+			deploymentId: "instance-001",
+			placementId: "placement-us-east-1",
 		},
 	},
 	{
@@ -102,8 +104,8 @@ export const mockMetricsGroups: MetricsGroup[] = [
 		dimensions: {
 			applicationId: "app-123-abc",
 			datetimeMinute: "2025-12-05T16:00:00Z",
-			deploymentId: "deploy-002",
-			placementId: "place-us-east-2",
+			deploymentId: "instance-002",
+			placementId: "placement-us-east-2",
 		},
 	},
 ];
@@ -167,8 +169,8 @@ export function createMockMetricsGroup(
 		dimensions: {
 			applicationId: "app-123-abc",
 			datetimeMinute: new Date().toISOString(),
-			deploymentId: "deploy-001",
-			placementId: "place-us-east-1",
+			deploymentId: "instance-001",
+			placementId: "placement-us-east-1",
 			...overrides.dimensions,
 		},
 	};