Instana on AWS Fargate

This page describes Instana's support for AWS ECS with the launch type Fargate. For using AWS ECS with the launch type EC2, please refer to our documentation on installing the host agent in AWS ECS on EC2. (Note: AWS Fargate on EKS is currently not supported.)

Node.js

Note: The support for Node.js applications on AWS Fargate is in technical preview.

The Node.js Fargate collector is delivered over a Docker agent image layer containing the collector files and an initialization script.

Add the following lines to your Dockerfile anywhere after the last FROM clause:

COPY --from=instana/aws-fargate-nodejs:latest /instana /instana
RUN /instana/setup.sh
ENV NODE_OPTIONS="--require /instana/node_modules/@instana/aws-fargate"

Build the container and push it to the image repository of your choice.

Finally, follow the configuration steps described in the section Configure Your Task Definition.

Note: If you are using Multi-stage builds (that is, if you have multiple FROM clauses in your Dockerfile), you need to add the lines below after the last FROM clause of your Dockerfile.

Note: Auto-profile of Node.js processes in AWS Fargate is not currently supported.

Getting The Node.js Layer From containers.instana.io Instead

The Docker layer is available publicly on dockerhub. If you also use Instana's Fargate support with other runtimes (like Java) for which the image layer is only avaible on our authenticated registry containers.instana.io and you want to keep things consistent, you can also get the Node.js Instana Fargate image layer from containers.instana.io instead of dockerhub. This is an alternative to the approach outlined above.

Since the containers.instana.io registry requires authentication, you need to execute the following command before using it in your Docker build:

docker login -u _ -p <your-agent-key> containers.instana.io

The placeholder <your-agent-key> needs to be replaced with your actual Instana agent key. This needs to happen on the machine where you build your Docker image.

With that out of the way, add the following lines to your Dockerfile anywhere after the last FROM clause:

COPY --from=containers.instana.io/instana/release/aws/fargate/nodejs:latest /instana /instana
RUN /instana/setup.sh
ENV NODE_OPTIONS="--require /instana/node_modules/@instana/aws-fargate"

.NET Core

Note: The support for .NET Core applications on AWS Fargate is in technical preview.

The way you make .NET Core tracing available in your Fargate containers is basically the same as for any other .NET Core containerized application. You have two options:

  1. Install NuGet packages in you application during development, or
  2. Install NuGet packages via Dockerfile

Install NuGet Packages during Development

You have to add the NuGet packages for the rewriter and the managed tracing extensions either to your project already at design-time, or only do this as part of your build when preparing your container-image.

Install the Rewriter

Based on the OS backing your container, you have to choose the right rewriter-package, as those are built from native code and targets specific system-libraries:

Install the Tracing Package

The packages listed above will also install the most recent version of the tracing-package that was available at the time when the rewriter-package has been released. However, we suggest explicitly adding the Instana Tracing Package for .NET Core too, which will give you more control over which version of it your application uses.

Configure the .NET Core Task Definition

Finally, follow the configuration steps described in the section Configure Your Task Definition, setting also the following environment variables:

  • CORECLR_ENABLE_PROFILING=1 (enables profiling of .NET Core)
  • CORECLR_PROFILER={cf0d821e-299b-5307-a3d8-b283c03916dd} (sets the clsid of the profiler to be used)
  • CORECLR_PROFILER_PATH=/app/instana_tracing/CoreProfiler.so (points to the library containing the profiler, which app assumed to be the path of your application)
  • DOTNET_STARTUP_HOOKS=/app/Instana.Tracing.Core.dll (metrics-collection and support of self-contained .NET Core applications)

Install NuGet packages in the Docker build

Here is an example of how the things discussed above can be used in a docker-container. Replace in the first line the right NuGet package postfix, using Alpine if you use a container image based on Alpine Linux, or Linux otherwise:

# after building the project, right before publishing, add the nuget-packages
RUN dotnet add <project_name>.csproj package Instana.Tracing.Core.Rewriter.<Linux|Alpine> --version <min-version 1.0.56>
RUN dotnet add <project_name>.csproj package Instana.Tracing.Core --version <min-version 1.1.46>
RUN dotnet publish -c Release -o out

# where the files will end up
WORKDIR /app
COPY --from=publish /src/out .

# set the env-vars as discussed above
ENV CORECLR_ENABLE_PROFILING=1
ENV CORECLR_PROFILER={cf0d821e-299b-5307-a3d8-b283c03916dd}
ENV CORECLR_PROFILER_PATH=/app/instana_tracing/CoreProfiler.so
ENV DOTNET_STARTUP_HOOKS=/app/Instana.Tracing.Core.dll

... # Other stuff in your Docker image

Finally, follow the configuration steps described in the section Configure Your Task Definition.

Go

The Go Fargate collector is included in github.com/instana/go-sensor starting from v1.14.0 and does not require additional configuration apart from setting up the environment variables described in Configure Your Task Definition section. The tracer detects that the app is running on AWS Fargate and activates the Fargate collector automatically.

Java

Note: The support for Java applications on AWS Fargate is in technical preview.

The Java Fargate collector is delivered over a Docker agent image containing the collector files.

The Docker layer is available on containers.instana.io. This Docker registry requires authentication. Before using it in you Docker build, please execute:

docker login -u _ -p <your-agent-key> containers.instana.io

The placeholder <your-agent-key> needs to be replaced with your actual Instana agent key. This needs to happen on the machine where you build your Docker image.

With that out of the way, add the following lines to your Dockerfile anywhere after the last FROM clause:

COPY --from=containers.instana.io/instana/release/aws/fargate/jvm:latest /instana /instana
ENV JAVA_TOOL_OPTIONS="-javaagent:/instana/instana-fargate-collector.jar"

Build the container and push it to the image repository of your choice.

Finally, follow the configuration steps described in the section Configure Your Task Definition.

Note: If you are using Multi-stage builds (that is, if you have multiple FROM clauses in your Dockerfile), you need to add the lines below after the last FROM clause of your Dockerfile.

Note: Auto-profile of Java processes in AWS Fargate is not currently supported.

Python

Coming soon!

Configure Your Task Definition

Note: These instructions are commons to the setup of all Instana collectors on AWS Fargate.

Note: Before following the steps described in this section, make sure you container images have been built according to the instructions specific to the runtime that your application uses listeed above in this page.

Note: If your application is based on .NET Core and you are installing the Instana NuGet packages at development time as described in the Install NuGet Packages during Development section, make sure you also set in your task definition the environment variables listed in the Configure the .NET Core Task Definition section.

All Instana collectors on AWS Fargate need a common set of configurations to be able to connect to and authenticate with the Instana backend:

  1. Create a new revision of the task definition:

    Creating a new Task Definition revision

  2. In the task definition configuration page, go to the container definition of your Node.js based container:

    Edit the container definition

  3. Add the following two environment variables to the container specification:

    • INSTANA_ENDPOINT_URL: Your This is your serverless monitoring endpoint. Make sure to use the correct value for your region that starts with https://serverless-.
    • INSTANA_AGENT_KEY: Your agent key.

    You can also obtain the correct values for these environment variables by going to your Instana installation, click on "... More" -> "Agents" -> "Installing Instana Agents" -> Platform: "AWS" -> Technology "AWS Fargate".

    Set environment variables in the container