Attribute Sensor for AWS Fargate (Java Edition)

This document outlines the information and configuration required to install the Attribute Sensor within an AWS Fargate task definition for Java applications.

The sensor runs as an embedded process inside your application's container. For Java applications it is paired with the Attribute Java agent, which is attached to the JVM so that TLS-encrypted traffic is visible for attribution. See the Attribute Java Instrumentation Guide for background on why Java requires the agent.

Step 1: Update containerDefinitions

In your task definition, modify the relevant containerDefinition as follows.

Add environment variables to the environment section:

"environment": [
  {
    "name": "CONFIG_ZPROBE_BEARER_TOKEN",
    "value": "<token>"
  },
  {
    "name": "CONFIG_ZPROBE_OTEL_ADDR",
    "value": "otel-endpoint.app.attrb.io:443"
  },
  {
    "name": "JAVA_TOOL_OPTIONS",
    "value": "-javaagent:/opt/zprobe/jagent.jar"
  }
]

Add a dependency to the dependsOn section:

"dependsOn": [
  {
    "containerName": "attribute-sensor",
    "condition": "COMPLETE"
  }
]

Add a mount to the mountPoints section:

"mountPoints": [
  {
    "sourceVolume": "attribute-shared",
    "containerPath": "/opt/zprobe"
  }
]

Change the entryPoint and command of the container:

"entryPoint": [
  "/opt/zprobe/launch/ecs-fargate"
],
"command": [
  "<start_command>"
]

注意

Replace <start_command> with your application's start command, split into one array element per argument — for example ["java", "-jar", "/app/app.jar"].

Add another container definition to containerDefinitions (sidecar):

{
  "name": "attribute-sensor",
  "image": "quay.io/attribute/sensor:<tag>",
  "essential": false,
  "entryPoint": [
    "/bin/sh",
    "-c"
  ],
  "command": [
    "mkdir -p /shared && cp -r /app/* /shared/"
  ],
  "mountPoints": [
    {
      "sourceVolume": "attribute-shared",
      "containerPath": "/shared"
    }
  ]
}

Step 2: Update volumes

Add the shared volume to the volumes section:

"volumes": [
  {
    "name": "attribute-shared"
  }
]

Notes

• It is recommended to create a new revision of your task definition when making these changes, then update your ECS service accordingly.

• Performance and availability:

  • The sensor runs as an embedded process within the container. We recommend increasing the CPU allocation by 1 vCPU to ensure minimal performance impact.
  • If the sensor fails, application functionality should not be affected.
  • Terraform automation for installation is supported.

Appendix A: Example of a Complete Task Definition

{
  "family": "<family>",
  "containerDefinitions": [
    {
      "name": "<image-name>",
      "image": "<image>",
      "environment": [
        {
          "name": "CONFIG_ZPROBE_BEARER_TOKEN",
          "value": "<token>"
        },
        {
          "name": "CONFIG_ZPROBE_OTEL_ADDR",
          "value": "otel-endpoint.app.attrb.io:443"
        },
        {
          "name": "JAVA_TOOL_OPTIONS",
          "value": "-javaagent:/opt/zprobe/jagent.jar"
        }
      ],
      "workingDirectory": "/app",
      "cpu": 0,
      "essential": true,
      "dependsOn": [
        {
          "containerName": "attribute-sensor",
          "condition": "COMPLETE"
        }
      ],
      "entryPoint": [
        "/opt/zprobe/launch/ecs-fargate"
      ],
      "command": [
        "java",
        "-jar",
        "/app/app.jar"
      ],
      "mountPoints": [
        {
          "sourceVolume": "attribute-shared",
          "containerPath": "/opt/zprobe"
        }
      ],
      "logConfiguration": {
        "logDriver": "awslogs",
        "options": {
          "awslogs-group": "/ecs/go-zprobe-fargate",
          "mode": "non-blocking",
          "awslogs-create-group": "true",
          "max-buffer-size": "25m",
          "awslogs-region": "us-east-1",
          "awslogs-stream-prefix": "ecs"
        }
      }
    },
    {
      "name": "attribute-sensor",
      "image": "quay.io/attribute/sensor:<tag>",
      "essential": false,
      "entryPoint": [
        "/bin/sh",
        "-c"
      ],
      "command": [
        "mkdir -p /shared && cp -r /app/* /shared/"
      ],
      "mountPoints": [
        {
          "sourceVolume": "attribute-shared",
          "containerPath": "/shared"
        }
      ]
    }
  ],
  "volumes": [
    {
      "name": "attribute-shared"
    }
  ],
  "executionRoleArn": "<role>",
  "networkMode": "awsvpc",
  "placementConstraints": [],
  "requiresCompatibilities": ["FARGATE"],
  "cpu": "4096",
  "memory": "8192",
  "runtimePlatform": {
    "cpuArchitecture": "X86_64",
    "operatingSystemFamily": "LINUX"
  },
  "enableFaultInjection": false
}

---

Trademarks: AWS is a trademark of Amazon.com, Inc. or its affiliates. All other trademarks are the property of their respective owners.