Amazon.CDK.AWS.ApplicationSignals.Alpha

AWS::ApplicationSignals Construct Library

The APIs of higher level constructs in this module are experimental and under active development. They are subject to non-backward compatible changes or removal in any future version. These are not subject to the Semantic Versioning model and breaking changes will be announced in the release notes. This means that while you may use them, you may need to update your source code when upgrading to a newer version of this package.

CloudWatch Application Signals is an auto-instrumentation solution built on OpenTelemetry that enables zero-code collection of monitoring data, such as traces and metrics, from applications running across multiple platforms. It also supports topology auto-discovery based on collected monitoring data and includes a new feature for managing service-level objectives (SLOs).

It supports Java, Python, .NET, and Node.js on platforms including EKS (and native Kubernetes), Lambda, ECS, and EC2. For more details, visit Application Signals on the AWS public website.

Application Signals Enablement L2 Constructs

A collection of L2 constructs which leverages native L1 CFN resources, simplifying the enablement steps and the creation of Application Signals resources.

ApplicationSignalsIntegration

ApplicationSignalsIntegration aims to address key challenges in the current CDK enablement process, which requires complex manual configurations for ECS customers. Application Signals is designed to be flexible and is supported for other platforms as well. However, the initial focus is on supporting ECS, with plans to potentially extend support to other platforms in the future.

Enable Application Signals on ECS with sidecar mode

1. Configure instrumentation to instrument the application with the ADOT SDK Agent.
2. Specify cloudWatchAgentSidecar to configure the CloudWatch Agent as a sidecar container.

using Constructs;
using Amazon.CDK.AWS.ApplicationSignals.Alpha;
using Amazon.CDK;
using Amazon.CDK.AWS.EC2;
using Amazon.CDK.AWS.ECS;

class MyStack : Stack
{
    public MyStack(Construct? scope=null, string? id=null, StackProps props=new StackProps { }) : base()
    {
        var vpc = new Vpc(this, "TestVpc", new VpcProps { });
        var cluster = new Cluster(this, "TestCluster", new ClusterProps { Vpc = vpc });

        var fargateTaskDefinition = new FargateTaskDefinition(this, "SampleAppTaskDefinition", new FargateTaskDefinitionProps {
            Cpu = 2048,
            MemoryLimitMiB = 4096
        });

        fargateTaskDefinition.AddContainer("app", new ContainerDefinitionOptions {
            Image = ContainerImage.FromRegistry("test/sample-app")
        });

        new ApplicationSignalsIntegration(this, "ApplicationSignalsIntegration", new ApplicationSignalsIntegrationProps {
            TaskDefinition = fargateTaskDefinition,
            Instrumentation = new InstrumentationProps {
                SdkVersion = JavaInstrumentationVersion.V2_10_0
            },
            ServiceName = "sample-app",
            CloudWatchAgentSidecar = new CloudWatchAgentOptions {
                ContainerName = "cloudwatch-agent",
                EnableLogging = true,
                Cpu = 256,
                MemoryLimitMiB = 512
            }
        });

        new FargateService(this, "MySampleApp", new FargateServiceProps {
            Cluster = cluster,
            TaskDefinition = fargateTaskDefinition,
            DesiredCount = 1
        });
    }
}

Enable Application Signals on ECS with daemon mode

Note: Since the daemon deployment strategy is not supported on ECS Fargate, this mode is only supported on ECS on EC2.

1. Run CloudWatch Agent as a daemon service with HOST network mode.
2. Configure instrumentation to instrument the application with the ADOT Python Agent.
3. Override environment variables by configuring overrideEnvironments to use service connect endpoints to communicate to the CloudWatch agent server

using Constructs;
using Amazon.CDK.AWS.ApplicationSignals.Alpha;
using Amazon.CDK;
using Amazon.CDK.AWS.EC2;
using Amazon.CDK.AWS.ECS;

class MyStack : Stack
{
    public MyStack(Construct? scope=null, string? id=null, StackProps props=new StackProps { }) : base(scope, id, props)
    {

        var vpc = new Vpc(this, "TestVpc", new VpcProps { });
        var cluster = new Cluster(this, "TestCluster", new ClusterProps { Vpc = vpc });

        // Define Task Definition for CloudWatch agent (Daemon)
        var cwAgentTaskDefinition = new Ec2TaskDefinition(this, "CloudWatchAgentTaskDefinition", new Ec2TaskDefinitionProps {
            NetworkMode = NetworkMode.HOST
        });

        new CloudWatchAgentIntegration(this, "CloudWatchAgentIntegration", new CloudWatchAgentIntegrationProps {
            TaskDefinition = cwAgentTaskDefinition,
            ContainerName = "ecs-cwagent",
            EnableLogging = false,
            Cpu = 128,
            MemoryLimitMiB = 64,
            PortMappings = new [] { new PortMapping {
                ContainerPort = 4316,
                HostPort = 4316
            }, new PortMapping {
                ContainerPort = 2000,
                HostPort = 2000
            } }
        });

        // Create the CloudWatch Agent daemon service
        // Create the CloudWatch Agent daemon service
        new Ec2Service(this, "CloudWatchAgentDaemon", new Ec2ServiceProps {
            Cluster = cluster,
            TaskDefinition = cwAgentTaskDefinition,
            Daemon = true
        });

        // Define Task Definition for user application
        var sampleAppTaskDefinition = new Ec2TaskDefinition(this, "SampleAppTaskDefinition", new Ec2TaskDefinitionProps {
            NetworkMode = NetworkMode.HOST
        });

        sampleAppTaskDefinition.AddContainer("app", new ContainerDefinitionOptions {
            Image = ContainerImage.FromRegistry("test/sample-app"),
            Cpu = 0,
            MemoryLimitMiB = 512
        });

        // No CloudWatch Agent side car is needed as application container communicates to CloudWatch Agent daemon through host network
        // No CloudWatch Agent side car is needed as application container communicates to CloudWatch Agent daemon through host network
        new ApplicationSignalsIntegration(this, "ApplicationSignalsIntegration", new ApplicationSignalsIntegrationProps {
            TaskDefinition = sampleAppTaskDefinition,
            Instrumentation = new InstrumentationProps {
                SdkVersion = PythonInstrumentationVersion.V0_8_0
            },
            ServiceName = "sample-app"
        });

        new Ec2Service(this, "MySampleApp", new Ec2ServiceProps {
            Cluster = cluster,
            TaskDefinition = sampleAppTaskDefinition,
            DesiredCount = 1
        });
    }
}

Enable Application Signals on ECS with replica mode

Note Running CloudWatch Agent service using replica mode requires specific security group configurations to enable communication with other services. For Application Signals functionality, configure the security group with the following minimum inbound rules: Port 2000 (HTTP) and Port 4316 (HTTP). This configuration ensures proper connectivity between the CloudWatch Agent and dependent services.

1. Run CloudWatch Agent as a replica service with service connect.
2. Configure instrumentation to instrument the application with the ADOT Python Agent.
3. Override environment variables by configuring overrideEnvironments to use service connect endpoints to communicate to the CloudWatch agent server

using Constructs;
using Amazon.CDK.AWS.ApplicationSignals.Alpha;
using Amazon.CDK;
using Amazon.CDK.AWS.EC2;
using Amazon.CDK.AWS.ECS;
using Amazon.CDK.AWS.ServiceDiscovery;

class MyStack : Stack
{
    public MyStack(Construct? scope=null, string? id=null, StackProps props=new StackProps { }) : base(scope, id, props)
    {

        var vpc = new Vpc(this, "TestVpc", new VpcProps { });
        var cluster = new Cluster(this, "TestCluster", new ClusterProps { Vpc = vpc });
        var dnsNamespace = new PrivateDnsNamespace(this, "Namespace", new PrivateDnsNamespaceProps {
            Vpc = vpc,
            Name = "local"
        });
        var securityGroup = new SecurityGroup(this, "ECSSG", new SecurityGroupProps { Vpc = vpc });
        securityGroup.AddIngressRule(securityGroup, Port.TcpRange(0, 65535));

        // Define Task Definition for CloudWatch agent (Replica)
        var cwAgentTaskDefinition = new FargateTaskDefinition(this, "CloudWatchAgentTaskDefinition", new FargateTaskDefinitionProps { });

        new CloudWatchAgentIntegration(this, "CloudWatchAgentIntegration", new CloudWatchAgentIntegrationProps {
            TaskDefinition = cwAgentTaskDefinition,
            ContainerName = "ecs-cwagent",
            EnableLogging = false,
            Cpu = 128,
            MemoryLimitMiB = 64,
            PortMappings = new [] { new PortMapping {
                Name = "cwagent-4316",
                ContainerPort = 4316,
                HostPort = 4316
            }, new PortMapping {
                Name = "cwagent-2000",
                ContainerPort = 2000,
                HostPort = 2000
            } }
        });

        // Create the CloudWatch Agent replica service with service connect
        // Create the CloudWatch Agent replica service with service connect
        new FargateService(this, "CloudWatchAgentService", new FargateServiceProps {
            Cluster = cluster,
            TaskDefinition = cwAgentTaskDefinition,
            SecurityGroups = new [] { securityGroup },
            ServiceConnectConfiguration = new ServiceConnectProps {
                Namespace = dnsNamespace.NamespaceArn,
                Services = new [] { new ServiceConnectService {
                    PortMappingName = "cwagent-4316",
                    DnsName = "cwagent-4316-http",
                    Port = 4316
                }, new ServiceConnectService {
                    PortMappingName = "cwagent-2000",
                    DnsName = "cwagent-2000-http",
                    Port = 2000
                } }
            },
            DesiredCount = 1
        });

        // Define Task Definition for user application
        var sampleAppTaskDefinition = new FargateTaskDefinition(this, "SampleAppTaskDefinition", new FargateTaskDefinitionProps { });

        sampleAppTaskDefinition.AddContainer("app", new ContainerDefinitionOptions {
            Image = ContainerImage.FromRegistry("test/sample-app"),
            Cpu = 0,
            MemoryLimitMiB = 512
        });

        // Overwrite environment variables to connect to the CloudWatch Agent service just created
        // Overwrite environment variables to connect to the CloudWatch Agent service just created
        new ApplicationSignalsIntegration(this, "ApplicationSignalsIntegration", new ApplicationSignalsIntegrationProps {
            TaskDefinition = sampleAppTaskDefinition,
            Instrumentation = new InstrumentationProps {
                SdkVersion = PythonInstrumentationVersion.V0_8_0
            },
            ServiceName = "sample-app",
            OverrideEnvironments = new [] { new EnvironmentExtension {
                Name = CommonExporting.OTEL_AWS_APPLICATION_SIGNALS_EXPORTER_ENDPOINT,
                Value = "http://cwagent-4316-http:4316/v1/metrics"
            }, new EnvironmentExtension {
                Name = TraceExporting.OTEL_EXPORTER_OTLP_TRACES_ENDPOINT,
                Value = "http://cwagent-4316-http:4316/v1/traces"
            }, new EnvironmentExtension {
                Name = TraceExporting.OTEL_TRACES_SAMPLER_ARG,
                Value = "endpoint=http://cwagent-2000-http:2000"
            } }
        });

        // Create ECS Service with service connect configuration
        // Create ECS Service with service connect configuration
        new FargateService(this, "MySampleApp", new FargateServiceProps {
            Cluster = cluster,
            TaskDefinition = sampleAppTaskDefinition,
            ServiceConnectConfiguration = new ServiceConnectProps {
                Namespace = dnsNamespace.NamespaceArn
            },
            DesiredCount = 1
        });
    }
}