Run yc-360 Script in Sidecar Container on AWS Fargate

You can deploy the yc-360 script alongside your Java application in the same Fargate Task using a sidecar container. This approach provides clear separation of concerns and simplifies observability integration.

Follow the steps below to run the yc-360 script as a sidecar in an AWS Fargate ECS Task.

1. Create Secrets for yc-360 Script Configuration

The yc-360 script requires a configuration file named yc-config.yaml. In ECS, you can store it in AWS Secrets Manager or SSM Parameter Store and reference it in the task definition.

The script supports multiple execution modes tailored for various monitoring needs. Select your preferred mode below to see how to configure the script.

Not sure what these modes mean? Learn more about Execution Modes

Secret Name: yc-config

version: "1"
options:
  k: {API_KEY}
  s: {http://MY_YC_SERVER:PORT}
  j: {JAVA_HOME}
  a: {APPLICATION_NAME}

Replace the placeholders in the YAML configuration file with your actual values:

• {API_KEY}: Your API key was provided with your license at the time of registration. If you're not sure where to find the API key, click here.
• {http://MY_YC_SERVER:PORT}: URL of the yCrash server (e.g., http://localhost:8080/).
• {JAVA_HOME}: The directory path where Java is installed in your environment.
• {APPLICATION_NAME}: Friendly name for the application (displayed in the yCrash dashboard).

For a full list of arguments, refer to the All yc-360 Script Arguments page.

This step is not required when running the yc-360 script in Only-capture mode.

Secret Name: yc-config

version: "1"
options:
  k: {API_KEY}
  s: {http://MY_YC_SERVER:PORT}
  j: {JAVA_HOME}
  kubernetes: true
  m3: true
  processTokens:
    - {TOKEN_TO_IDENTIFY_PROCESS}${APPLICATION_NAME}
  accessLogs:
    - {ACCESS_LOG_PATH}${APPLICATION_NAME}
  accessLogFormats:
    - {ACCESS_LOG_FORMAT}${APPLICATION_NAME}

Replace the placeholders in the YAML configuration file with your actual values:

• {API_KEY}: Your API key was provided with your license at the time of registration. If you're not sure where to find the API key, click here.
• {http://MY_YC_SERVER:PORT}: URL of the yCrash server (e.g., http://localhost:8080/).
• {JAVA_HOME}: The directory path where Java is installed in your environment.
• {TOKEN_TO_IDENTIFY_PROCESS}: A unique keyword to identify your Java process. To learn more about this argument, click here.
• {APPLICATION_NAME}: Friendly name for the application (displayed in the yCrash dashboard).
• {ACCESS_LOG_PATH}: Full path to the application’s access log file (e.g., /var/log/nginx/access.log). To learn more about this argument, click here.
• {ACCESS_LOG_FORMAT}: Log format pattern used in the access log to capture response time (e.g., %h %l %u %t %r %s %b %D).

For a full list of arguments, refer to the All yc-360 Script Arguments page.

2. Deploy BuggyApp and yc-360 Script on ECS Fargate

In this step, you’ll deploy both the Java application (BuggyApp) and the yc-360 script as containers in the same ECS task.

Overview

This deployment includes:

• yc-360 Script (opens new window): Collects performance metrics from the application.
• BuggyApp (opens new window): A sample Java application simulating performance scenarios. Replace with your own Java app as needed.

Key Points

• Task Definition: Both containers (BuggyApp and yc-360) run under the same Fargate Task.
• Volumes: Shared /tmp directory between containers for temporary data.
• Ports:
  • yc-360 Script listens on 8085.
  • BuggyApp listens on 9010.

ECS Task Definition (Example)

{
    "family": "task-buggyapp-yc360",
    "pidMode": "task",
    "containerDefinitions": [
        {
            "command": [
                "-showversion",
                "-verbose:gc",
                "-Xmx256m",
                "-Xlog:gc:jvm_gc.%p.log",
                "-DlogDir=.",
                "-DuploadDir=.",
                "-Dapp=BuggyApp",
                "-jar",
                "buggyApp.jar",
                "sample"
            ],
            "cpu": 256,
            "environment": [],
            "environmentFiles": [],
            "essential": true,
            "image": "ycrash/buggyapp:latest",
            "user": "0",
            "logConfiguration": {
                "logDriver": "awslogs",
                "options": 
                {
                    "awslogs-create-group": "true",
                    "awslogs-group": "/ecs/yc-apps",
                    "awslogs-region": "us-west-1",
                    "awslogs-stream-prefix": "ba"
                }
            },
            "memory": 1024,
            "memoryReservation": 1024,
            "mountPoints": [
                {
                    "containerPath": "/tmp",
                    "readOnly": false,
                    "sourceVolume": "shared-tmp"
                }
            ],
            "name": "buggyapp",
            "portMappings": [
                {
                    "appProtocol": "http",
                    "containerPort": 8080,
                    "name": "buggyapp-8080-tcp",
                    "protocol": "tcp"
                }
            ],
            "systemControls": [],
            "ulimits": [],
            "volumesFrom": []
        },
        {
            "command": [
                "-s",
                "{YC_SERVER_URL}}",
                "-j",
                "/opt/java/openjdk",
                "-k",
                "{API_KEY}",
                "-m3",
                "-processTokens",
                "{JAVA_PROCESS_IDENTIFIER}${APP_NAME}}",
                "-m3Frequency", 
                "3m",
                "-kubernetes",
                "-address",
                "0.0.0.0",
                "-port",
                "8085",
                "-tags",
                "{TAG_NAME}"
            ],
            "cpu": 256,
            "entryPoint": [
                "./yc"
            ],
            "environment": [],
            "environmentFiles": [],
            "essential": false,
            "image": "ycrash/yc-agent:latest",
            "user": "0",
            "logConfiguration": {
                "logDriver": "awslogs",
                "options": 
                {
                    "awslogs-create-group": "true",
                    "awslogs-group": "/ecs/yc-apps",
                    "awslogs-region": "us-west-1",
                    "awslogs-stream-prefix": "yc"
                }
            },
            "memory": 1024,
            "memoryReservation": 1024,
            "mountPoints": [
                {
                    "containerPath": "/tmp",
                    "readOnly": false,
                    "sourceVolume": "shared-tmp"
                }
            ],
            "name": "yc-360-script",
            "portMappings": [
                {
                    "appProtocol": "http",
                    "containerPort": 8085,
                    "name": "yc360-8085-tcp",
                    "protocol": "tcp"
                }
            ],
            "systemControls": [],
            "volumesFrom": []
        }
    ],
    "taskRoleArn": "arn:aws:iam::{AWS_ACCOUNT_ID}:role/ecsTaskExecutionRole",
    "executionRoleArn": "arn:aws:iam::{AWS_ACCOUNT_ID}:role/ecsTaskExecutionRole",
    "networkMode": "awsvpc",
    "volumes": [
        {
            "host": {},
            "name": "shared-tmp"
        }
    ],
    "placementConstraints": [],
    "requiresCompatibilities": [
        "FARGATE"
    ],
    "cpu": "512",
    "memory": "2048",
    "runtimePlatform": {
        "cpuArchitecture": "ARM64",
        "operatingSystemFamily": "LINUX"
    },
    "enableFaultInjection": false
}

Deploy the ECS Task

1. Register the task definition:

aws ecs register-task-definition --cli-input-json file://task-buggyapp-yc360.json

2. Run the task in a Fargate cluster:

aws ecs run-task \
  --cluster yc-fargate-cluster \
  --launch-type FARGATE \
  --network-configuration "awsvpcConfiguration={subnets=[subnet-12345678],assignPublicIp=ENABLED}" \
  --task-definition task-buggyapp-yc360

Notes

• Ensure the ECS Task Execution Role has permissions to pull images and write logs to CloudWatch.
• The shared /tmp volume allows the yc-360 script to interact with the BuggyApp container.
• Adjust CPU and memory values based on your application’s resource requirements.

3. Execute yc-360 Script

The script supports multiple execution modes tailored for various monitoring needs. Select your preferred mode below to see how to configure the script.

Not sure what these modes mean? Learn more about Execution Modes

aws ecs execute-command \
  --cluster {CLUSTER_NAME} \
  --task {TASK_ID} \
  --container yc-360-script \
  --command "sh" \
  --interactive

./yc -s {http://MY_YC_SERVER:PORT} -j /opt/java/openjdk -k {API_KEY} -a {APPLICATION_NAME} -tags {TAG_NAMe} -p {PID}

To run the yc-360 script in this mode, pass the -onlyCapture argument to the script.

aws ecs execute-command \
  --cluster {CLUSTER_NAME} \
  --task {TASK_ID} \
  --container yc-360-script \
  --command "sh" \
  --interactive

./yc -j /opt/java/openjdk -onlyCapture -tags fargate-tramsmitted -p {JAVA_PID}

When you run the yc-360 script container in M3 Mode, it automatically reads the yc-config.yaml file and executes the yc-360 script.

IMPORTANT NOTE

• To detect memory-related issues, GC logging must be enabled for your application. You can enable GC logging by using the JVM arguments listed here.

• The yc-360 script doesn't capture heap dump by default. Pass -hd argument to capture heap dump. For more information, please visit How to Capture Heap Dump?