Skip to main content

Sensor on AWS Fargate

Prerequisites​

Before installing the PCAP sensor, ensure you have:

  • AWS profile access key and secret access key saved at path ~/.aws/credentials
  • The profile should have all the required permissions as listed here
  • Existing ECS Task Definition: The PCAP sensor is installed as a sidecar into an existing application task
    • Task Family Name: The name of your application's ECS task definition (e.g., my-app-task, httpbin, api-service)
    • Find it in: AWS Console → ECS → Task Definitions, or run aws ecs list-task-definition-families --region <region>
  • Levo Satellite URL: The endpoint where your Levo Satellite is running
    • Format: http://<satellite-ip>:8080 or https://<satellite-domain>:8080
    • Get it from: Satellite installation output or AWS Console → ECS → Clusters → Tasks → Network bindings
    • Example: http://10.0.0.1:8080 (private IP) or http://52.32.232.165:8080 (public IP)
  • IAM Role (Application Task): Your application's ECS task must have an IAM role with permissions for SQS (sending traces), CloudWatch Logs (logging), and ECR (pulling images). The PCAP sensor runs as a sidecar and automatically inherits this IAM role - no separate role is needed for the sensor.
IAM Role Inheritance

The PCAP sensor does not require its own IAM role. It automatically inherits the IAM role from your application task. If your application task already has an IAM role with SQS, CloudWatch Logs, and ECR permissions, you're all set. If not, you can use the same IAM role created during Satellite installation or create one with the required permissions.

Install​

The PCAP Sensor is installed as a sidecar on an existing ECS task definition. Choose the method that fits your workflow:

Add the PCAP Sensor as a sidecar to an existing task definition via the AWS Console:

  • Go to Task Definitions
  • Select the required task definition
  • Click on Create revision with JSON
  • Add the given JSON object under containerDefinitions
  • Replace the values for satellite-url, levo-env, and levoai-org-id in entryPoint
  • Replace the values for environment and logConfiguration as per your requirement
  • Set the cpu limit as number of CPU Units (Note: 1 core = 1024 CPU Units)
  • Set the memory limit in MiB (Note: memory should not exceed the Task memory limit)

{
  "name": "levo-pcap-sensor",
  "image": "levoai/pcap-sensor:0.4.8",
  "cpu": 512,
  "memory": 512,
  "portMappings": [],
  "essential": false,
  "entryPoint": [
      "./bin/init",
      "apidump",
      "--satellite-url",
      "< INSERT SATELLITE URL (http(s)://hostname|IP:port) >",
      "--levo-env",
      "<INSERT APPLICATION ENVIRONMENT (staging, production etc.)>",
      "--levoai-org-id",
      "< INSERT LEVO ORG ID >",
      "--rate-limit",
      "<INSERT NUMBER OF TRACES PER MINUTE>"
  ],
  "environment": [
      {
          "name": "LEVO_AWS_REGION",
          "value": "< INSERT AWS REGION (us-west-2) >"
      }
  ],
  "mountPoints": [],
  "volumesFrom": [],
  "logConfiguration": {
      "logDriver": "awslogs",
      "options": {
          "awslogs-group": "< INSERT LOGS IDENTIFIER (/ecs/your-application-pcap) >",
          "awslogs-create-group": "true",
          "awslogs-region": "< INSERT AWS REGION (us-west-2) >",
          "awslogs-stream-prefix": "ecs-pcap"
      }
  }
}

Additional Flags​

Specify additional flags in the sensor entrypoint (applicable to all installation methods):

--trace-export-interval     # default 10s
--rate-limit                # number of traces per minute
--filter                    # e.g., port 8080 and (not port 8081)
--host-allow                # regex for allowed hosts
--path-allow                # regex for allowed paths
--host-exclusions           # regex for excluded hosts
--path-exclusions           # regex for excluded paths

Configure Sensor Memory and CPU Resource Limits​

  • For normal/average use cases, use the default configuration (5% CPU and memory)
  • For strict resource constraints, use the Low Resource JSON File

Filter Out Traffic​

If you need to ignore traffic from other sidecars in the AWS task, use the --filter flag to ignore traffic on non-essential container ports.

Example: --filter "not port 8888"

AWS Permissions needed​

Add the AmazonECS_FullAccess policy to get access to all the necessary permissions.

ActionResourcePurpose
ec2:DescribeRegions*Find the list of AWS regions you have enabled. (If not present, defaults to a precompiled list.)
ecs:ListClusters*Find the available ECS clusters.
ecs:DescribeClusters*, or restricted to account like arn:aws:ecs:::cluster/*Look up the names of the available ECS clusters.
ecs:ListTaskDefinitionFamilies*Find the available task definitions.
ecs:DescribeTaskDefinition*Read the existing task definition in order to copy it.
ecs:RegisterTaskDefinition*Write a new version of the task definition.
ecs:ListServices*Find the available services.
ecs:DescribeServices*, or restricted to your account, or restricted to the cluster you selectedIdentify which services are using the task definition you selected.
ecs:UpdateService*, or restricted to your account, or restricted to the cluster you selectedUpdate and restart the service using the new task definition.
ecs:TagResource*, or restricted to your account, or restricted to the cluster you selectedMark the service as having been updated by Levo.ai.

Viewing PCAP Sensor Logs​

The PCAP Sensor writes logs to CloudWatch. By default, it automatically inherits the log configuration from your application container, ensuring logs are centralized in the same location.

How Log Configuration Works​

The sensor uses the following logic to determine its log configuration:

  1. If --log-group is specified: Uses the custom log group you provide
  2. If your application has a log configuration: Inherits the application's log group and settings, only changing the stream prefix to ecs-pcap for easy identification
  3. If no log configuration exists: Falls back to /ecs/<task-family> with auto-creation enabled

This means:

  • ✅ Sensor logs appear in the same CloudWatch log group as your application
  • ✅ Sensor logs use the same region and retention settings as your application
  • ✅ Sensor logs are easily identifiable with the ecs-pcap stream prefix
Log Configuration Inheritance

You don't need to configure logging for the sensor separately. It automatically inherits your application's CloudWatch log configuration, making it easy to view all logs in one place.

Log Location​

  • Log Group: Same as your application (e.g., /ecs/my-app-task, /ecs/httpbin)
  • Log Stream Prefix: ecs-pcap/levo-pcap-sensor/
  • Log Format: Timestamped INFO-level messages showing sensor health, trace capture, and export status

Download the log viewer script from the Satellite documentation:

curl -O https://docs.levo.ai/artifacts/satellite/levo-logs.sh
chmod +x levo-logs.sh

View PCAP sensor logs (replace <YOUR_CLUSTER>, <YOUR_LOG_GROUP>, and <YOUR_REGION> with your values):

# View sensor logs from your application's log group
./levo-logs.sh pcap-sensor \
  --cluster <YOUR_CLUSTER> \
  --log-group <YOUR_LOG_GROUP> \
  --region <YOUR_REGION>

# Example: View httpbin sensor logs
./levo-logs.sh pcap-sensor \
  --cluster my-ecs-cluster \
  --log-group /ecs/httpbin \
  --region us-east-1

# View logs from the last 10 minutes without following
./levo-logs.sh pcap-sensor \
  --cluster my-ecs-cluster \
  --log-group /ecs/httpbin \
  --region us-east-1 \
  --since 10m \
  --no-follow

Using AWS CLI Directly​

# View sensor logs only (replace <YOUR_LOG_GROUP> and <YOUR_REGION>)
aws logs tail <YOUR_LOG_GROUP> \
  --log-stream-name-prefix ecs-pcap/levo-pcap-sensor/ \
  --follow --format short --region <YOUR_REGION>

# Example
aws logs tail /ecs/httpbin \
  --log-stream-name-prefix ecs-pcap/levo-pcap-sensor/ \
  --follow --format short --region us-east-1

Using AWS Console​

  1. Navigate to CloudWatch → Log groups
  2. Select your application's log group (e.g., /ecs/httpbin)
  3. Use the filter dropdown to select streams starting with ecs-pcap/levo-pcap-sensor/
  4. Or use the search bar to filter by text (e.g., "traces captured", "exported spans")

What to Look For​

Healthy sensor logs:

[INFO] sensor-health: request successful, status 200
[INFO] 15 traces captured on interface eth1
[INFO] Successfully exported spans to satellite
Was this page helpful?