Captures Cloudformation nested stack deploy events as traces

Before you start, you'll need to have an AWS access key and secret on hand, as well as the name of a Cloudformation stack you have permissions to call the DescribeStackEvents API on.

Use one of the following sets of commands, depending on your operating system. Alternatively you can download the zip directly from the releases page.

wget https://github.com/Grunet/cfn-trace/releases/latest/download/cfn-trace-x86_64-unknown-linux-gnu.zip
unzip cfn-trace-x86_64-unknown-linux-gnu.zip
rm cfn-trace-x86_64-unknown-linux-gnu.zip

Leaves a binary named cfn-trace in the current working directory.

Invoke-WebRequest https://github.com/Grunet/cfn-trace/releases/latest/download/cfn-trace-x86_64-pc-windows-msvc.zip -OutFile ./cfn-trace-x86_64-pc-windows-msvc.zip
Expand-Archive -LiteralPath .\cfn-trace-x86_64-pc-windows-msvc.zip -DestinationPath .\
rm .\cfn-trace-x86_64-pc-windows-msvc.zip

Leaves an executable named cfn-trace.exe in the current working directory.

curl -OL https://github.com/Grunet/cfn-trace/releases/latest/download/cfn-trace-x86_64-apple-darwin.zip
unzip ./cfn-trace-x86_64-apple-darwin.zip
rm ./cfn-trace-x86_64-apple-darwin.zip

Leaves a binary named cfn-trace in the current working directory.

curl -OL https://github.com/Grunet/cfn-trace/releases/latest/download/cfn-trace-aarch64-apple-darwin.zip
unzip ./cfn-trace-aarch64-apple-darwin.zip
rm ./cfn-trace-aarch64-apple-darwin.zip

Leaves a binary named cfn-trace in the current working directory.

If you can use Docker and Docker Compose, the following should get you setup. Otherwise check out its official docs for alternative approaches.

Create a docker-compose.yaml file and a config.yaml file in the same directory.

docker-compose.yaml

version: "3.9"
services:
  otel-collector:
    image: otel/opentelemetry-collector:0.50.0 # The specific version here is unimportant, as long as some tag is specified (otherwise the volume mount won't work)
    volumes:
      - ./config.yaml:/etc/otelcol/config.yaml
    ports:
      - "4318:4318"

config.yaml

receivers:
  otlp:
    protocols:
      http:
        endpoint: 0.0.0.0:4318

processors:
  batch:

exporters:
  logging:
    loglevel: debug

service:
  pipelines:
    traces:
      receivers: [otlp]
      processors: [batch]
      exporters: [logging]

Then start the collector by running docker compose up from this directory.

For the moment, the only way to pass AWS credentials and the region for the binary to use is via environment variables.

In a new shell, setup the following environment variables (defined in this AWS doc), after replacing the dummy values with your own.

export AWS_ACCESS_KEY_ID=AKIAIOSFODNN7EXAMPLE
export AWS_SECRET_ACCESS_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
export AWS_DEFAULT_REGION=us-west-2

$Env:AWS_ACCESS_KEY_ID="AKIAIOSFODNN7EXAMPLE"
$Env:AWS_SECRET_ACCESS_KEY="wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY"
$Env:AWS_DEFAULT_REGION="us-west-2"

In this new shell with the AWS environment variables present, run the following command, after replacing the dummy value with your own.

./cfn-trace --stack-name <your root stack's name>

The collector's shell should be displaying raw trace/span information.

.\cfn-trace.exe --stack-name <your root stack's name>

The collector's shell should be displaying raw trace/span information.

The details will vary from vendor to vendor, but in general this should only require tweaking the config.yaml file to include a vendor-specific exporter (e.g. for Honeycomb, you can see on page 19 of this doc what tweaks are needed to send the data to them).

There isn't a --help argument yet, but here is a list of the arguments that are available

• --debug - this will turn on debug-level logging (mostly intended for troubleshooting)
• --stack-name - set this to the name of a root Cloudformation stack to generate a trace from its most recent deploy
• --version - this will echo the version of the binary to the console

The Sigstore project's cosign tool was used to sign the zips of the binaries. To check for post-publish tamperment, you'll need to install cosign first.

Using the zip for Linux as an example, here is how you can do the check.

wget https://github.com/Grunet/cfn-trace/releases/latest/download/cfn-trace-x86_64-unknown-linux-gnu.zip
wget https://github.com/Grunet/cfn-trace/releases/latest/download/cfn-trace-x86_64-unknown-linux-gnu.zip.pem
wget https://github.com/Grunet/cfn-trace/releases/latest/download/cfn-trace-x86_64-unknown-linux-gnu.zip.sig
cosign verify-blob --cert ./cfn-trace-x86_64-unknown-linux-gnu.zip.pem --signature ./cfn-trace-x86_64-unknown-linux-gnu.zip.sig ./cfn-trace-x86_64-unknown-linux-gnu.zip

If it hasn't been tampered with, you should see the text "Verified OK" show up in the output.

As of this writing, Deno doesn't support gRPC, meaning JSON-encoded protobuf format via OTLP/HTTP is its only option for exporting OpenTelemetry data (like is the case for browsers). However, this is still classified as experimental, so vendors have not implemented ways to directly receive it yet (as far as I am aware).

However, the OpenTelemetry Collector is able to receive it, and then transform it into a format that can be sent to a vendor. Hence why it is needed, as a workaround for the time being.

The easiest way to get started playing with the repository is to click on the above link and create a (free) Gitpod account using your Github credentials. This will open a workspace in your browser that should have all of the necessary tools ready to go (you can do the same from a fork if you're working on a PR, just use your fork's repository in the URL instead of this one's.)

FYI there are no commit hooks or CI commands currently that will save and re-commit any changes made by the code auto-formatter, so you may have to run make format before you finish a PR to work around this.