Search across all documentation pages
When traffic is mysteriously dropped or an instance is talking to somewhere it should not, you need to see the traffic. VPC Flow Logs record metadata for every IP flow in your VPC - source, destination, ports, bytes, and whether it was accepted or rejected.
This page enables flow logs from the SDK to both CloudWatch Logs and S3, explains the IAM and format choices, and shows how to query the results to answer real questions.
The common setup is flow logs on a whole VPC delivered to a CloudWatch Logs group. This needs an IAM role that grants the flow-logs service permission to write - passed as DeliverLogsPermissionArn.
# --- Python (boto3) ---
import boto3
ec2 = boto3.client("ec2", region_name="us-east-1")
resp = ec2.create_flow_logs(
ResourceIds=["vpc-0abc123"],
ResourceType="VPC",
TrafficType="ALL",
LogDestinationType="cloud-watch-logs",
LogGroupName="/vpc/flowlogs",
DeliverLogsPermissionArn="arn:aws:iam::111122223333:role/flow-logs-role",
)
print(resp["FlowLogIds"])// --- TypeScript (AWS SDK v3) ---
import { EC2Client, CreateFlowLogsCommand } from "@aws-sdk/client-ec2";
const ec2 = new EC2Client({ region: "us-east-1" });
const resp = await ec2.send(new CreateFlowLogsCommand({
ResourceIds: ["vpc-0abc123"],
ResourceType: "VPC",
TrafficType: "ALL",
LogDestinationType: "cloud-watch-logs",
LogGroupName: "/vpc/flowlogs",
DeliverLogsPermissionArn: "arn:aws:iam::111122223333:role/flow-logs-role",
}));
console.log(resp.FlowLogIds);ResourceType can be VPC, Subnet, or NetworkInterface, scoping the logs from broad to narrow. TrafficType of ALL captures both accepted and rejected flows; the IAM role must trust vpc-flow-logs.amazonaws.com and allow logs:CreateLogStream and logs:PutLogEvents.
Delivering to S3 instead of CloudWatch Logs is cheaper for high volume and needs no IAM role - just a bucket whose policy allows the log-delivery service to write. This variant also narrows to REJECT traffic, the fastest way to hunt blocked connections.
# --- Python (boto3) ---
import boto3
ec2 = boto3.client("ec2", region_name="us-east-1")
resp = ec2.create_flow_logs(
ResourceIds=["subnet-0priv1"],
ResourceType="Subnet",
TrafficType="REJECT",
LogDestinationType="s3",
LogDestination="arn:aws:s3:::my-flow-logs-bucket/vpc/",
)
print(resp["FlowLogIds"], resp["Unsuccessful"])// --- TypeScript (AWS SDK v3) ---
import { EC2Client, CreateFlowLogsCommand } from "@aws-sdk/client-ec2";
const ec2 = new EC2Client({ region: "us-east-1" });
const resp = await ec2.send(new CreateFlowLogsCommand({
ResourceIds: ["subnet-0priv1"],
ResourceType: "Subnet",
TrafficType: "REJECT",
LogDestinationType: "s3",
LogDestination: "arn:aws:s3:::my-flow-logs-bucket/vpc/",
}));
console.log(resp.FlowLogIds, resp.Unsuccessful);Note LogDestination (an S3 ARN) replaces LogGroupName + DeliverLogsPermissionArn. Always check the Unsuccessful array in the response - CreateFlowLogs can partially fail per resource and still return 200, so an empty Unsuccessful is your confirmation.
Each record is a line of space-separated fields. The default format captures the 5-tuple and outcome: version, account id, interface id, source and destination address, source and destination port, protocol, packets, bytes, start and end time, action (ACCEPT / REJECT), and log status. The action field is what tells you a security group or NACL dropped the flow.
Crucially, flow logs are metadata, not packet capture. They record that 10.0.1.5 sent 4 KB to 52.10.0.5:443 and it was accepted - never the payload. For packet contents you need Traffic Mirroring, a separate feature.
You can capture extra fields (like pkt-srcaddr, pkt-dstaddr for the real source behind NAT, tcp-flags, or flow-direction) with a custom format string. Pass it as LogFormat with ${field} tokens.
# --- Python (boto3) ---
ec2.create_flow_logs(
ResourceIds=["vpc-0abc123"], ResourceType="VPC", TrafficType="ALL",
LogDestinationType="cloud-watch-logs", LogGroupName="/vpc/flowlogs",
DeliverLogsPermissionArn="arn:aws:iam::111122223333:role/flow-logs-role",
LogFormat="${srcaddr} ${dstaddr} ${dstport} ${action} ${tcp-flags}",
MaxAggregationInterval=60, # 60s aggregation for finer granularity
)// --- TypeScript (AWS SDK v3) ---
import { CreateFlowLogsCommand } from "@aws-sdk/client-ec2";
await ec2.send(new CreateFlowLogsCommand({
ResourceIds: ["vpc-0abc123"], ResourceType: "VPC", TrafficType: "ALL",
LogDestinationType: "cloud-watch-logs", LogGroupName: "/vpc/flowlogs",
DeliverLogsPermissionArn: "arn:aws:iam::111122223333:role/flow-logs-role",
LogFormat: "${srcaddr} ${dstaddr} ${dstport} ${action} ${tcp-flags}",
MaxAggregationInterval: 60, // 60s aggregation for finer granularity
}));MaxAggregationInterval is 600 seconds by default; set it to 60 when you need finer timing at the cost of more log volume.
Logs in CloudWatch are queryable with Logs Insights via StartQuery / GetQueryResults on the logs client. This finds the top REJECTed destinations - a quick triage for blocked traffic.
# --- Python (boto3) ---
import boto3, time
logs = boto3.client("logs", region_name="us-east-1")
q = logs.start_query(
logGroupName="/vpc/flowlogs",
startTime=int(time.time()) - 3600, endTime=int(time.time()),
queryString="filter action='REJECT' | stats count(*) as hits by dstAddr, dstPort "
"| sort hits desc | limit 20",
)
time.sleep(3)
print(logs.get_query_results(queryId=q["queryId"])["results"])// --- TypeScript (AWS SDK v3) ---
import { CloudWatchLogsClient, StartQueryCommand, GetQueryResultsCommand } from "@aws-sdk/client-cloudwatch-logs";
const logs = new CloudWatchLogsClient({ region: "us-east-1" });
const now = Math.floor(Date.now() / 1000);
const q = await logs.send(new StartQueryCommand({
logGroupName: "/vpc/flowlogs",
startTime: now - 3600, endTime: now,
queryString: "filter action='REJECT' | stats count(*) as hits by dstAddr, dstPort " +
"| sort hits desc | limit 20",
}));
await new Promise((r) => setTimeout(r, 3000));
const res = await logs.send(new GetQueryResultsCommand({ queryId: q.queryId! }));
console.log(res.results);Insights queries are asynchronous: StartQuery returns a queryId, and you poll GetQueryResults until status is Complete. For S3-delivered logs you query with Athena instead.
vpc-flow-logs.amazonaws.com. Without it, CreateFlowLogs reports the resource in Unsuccessful.Unsuccessful array. The call can partially fail and still return successfully; check that array to confirm each resource actually got a flow log.ALL logging to CloudWatch can be expensive; use S3 for bulk retention and REJECT-only or subnet scope to trim volume.Enable REJECT flow logs on sensitive subnets for cheap security visibility, add ALL to S3 for forensics and retention, and reach for Traffic Mirroring only when you truly need packet contents.
Metadata for each IP flow - source and destination address and port, protocol, packet and byte counts, time window, and whether the flow was accepted or rejected. Not the packet contents.
No. They are metadata only. For actual packet contents use Traffic Mirroring, a separate feature.
A whole VPC, a single subnet, or an individual network interface - set by ResourceType as VPC, Subnet, or NetworkInterface.
For CloudWatch Logs delivery yes - a role passed as DeliverLogsPermissionArn that trusts the flow-logs service. For S3 delivery you need only a bucket policy, no role.
TrafficType filters which flows are logged: everything, only accepted, or only rejected. REJECT is the quickest way to find traffic a security group or NACL blocked.
Delivery lags - a few minutes for CloudWatch, up to ten for S3. Also check the Unsuccessful array in the create response in case the resource failed to attach.
For CloudWatch-delivered logs use Logs Insights via StartQuery/GetQueryResults. For S3-delivered logs use Athena over the stored files.
Yes. Pass a LogFormat string with ${field} tokens to capture extras like pkt-srcaddr, tcp-flags, or flow-direction beyond the default fields.
Deliver bulk logs to S3 rather than CloudWatch, log only REJECT where you just need blocked-traffic visibility, and scope to a subnet or ENI instead of the whole VPC.
Stack versions: This page was written for boto3 1.43.x (Python 3.10+) and the AWS SDK for JavaScript v3 (Node.js 18+).
Reviewed by Chris St. John·Last updated Jul 23, 2026