Apache SkyWalking APM on AWS User Guide

Overview

This image runs Apache SkyWalking 10.4, an open-source Application Performance Monitoring (APM) and observability platform. SkyWalking collects distributed traces, service and instance metrics, and logs from your applications and visualizes service topology, latency, throughput and error rates in a built-in web UI.

The appliance runs as a single-node topology under a dedicated unprivileged skywalking system account, managed by systemd, on Eclipse Temurin JDK 17. Three cooperating services make up the stack:

• skywalking-oap.service - the OAP (Observability Analysis Platform) backend. It exposes agent receivers on gRPC port 11800 and HTTP port 12800; the HTTP port also hosts the GraphQL query API the UI consumes.
• skywalking-ui.service - the SkyWalking web UI, bound to the loopback interface on port 8080 and fronted by nginx.
• skywalking-banyandb.service - Apache BanyanDB, the storage engine the SkyWalking 10.x line is designed around, running standalone and bound to the loopback interface on gRPC port 17912.

The storage engine is Apache BanyanDB, licensed entirely under Apache-2.0 - the observability database the SkyWalking project builds for exactly this purpose - so every component of the appliance is open source and redistributable. All telemetry storage, plus the OAP and UI logs, live on a dedicated EBS volume mounted at /var/lib/skywalking, separate from the operating system disk and independently resizable.

The SkyWalking UI has no strong built-in authentication, so it is bound to loopback and fronted by an nginx reverse proxy on port 80 that enforces HTTP basic authentication. This image does not ship a shared password: a one-shot first-boot service generates a unique UI password on every instance and writes it to /root/apache-skywalking-credentials.txt with mode 0600. nginx also serves an unauthenticated /health endpoint for liveness probes.

The security group opens SSH (port 22) and the nginx-fronted UI (port 80). The UI (8080), the OAP receivers (11800, 12800) and the BanyanDB datastore (17912) are not opened to the internet by the default security group. When you are ready to send telemetry, you open the OAP receiver ports to your own application or agent network range, as described below.

Prerequisites

Before you deploy this image you need:

• An Amazon Web Services account where you can launch EC2 instances
• IAM permissions to launch instances, create security groups, and subscribe to AWS Marketplace products
• An EC2 key pair in the target Region for SSH access to the instance
• A VPC and subnet in the target Region, with a security group allowing inbound port 22 from your management network and port 80 from where you will reach the UI
• An SSH client and a web browser on your workstation

Launching from the AWS Marketplace

1. Open the product page in AWS Marketplace and choose Continue to Subscribe
2. Accept the terms, then choose Continue to Configuration
3. Select the software version and the Region you want to deploy into, then choose Continue to Launch
4. Choose Launch through EC2 for full control of networking and storage
5. Pick an instance type. m5.large is the recommended minimum; scale up as your trace and metric volume grow, since the OAP backend and BanyanDB are memory-hungry
6. Select your VPC, subnet, key pair and a security group that allows inbound 22 (SSH) from your management network and 80 (UI) from where you will browse
7. Launch the instance and wait for the status checks to pass

Launching from the AWS CLI

You can launch the same AMI from the command line. Replace the AMI ID, key name, subnet and security group with your own values:

aws ec2 run-instances \
  --image-id <ami-id> \
  --instance-type m5.large \
  --key-name your-key \
  --subnet-id <subnet-id> \
  --security-group-ids <security-group-id> \
  --tag-specifications 'ResourceType=instance,Tags=[{Key=Name,Value=skywalking}]'

Connecting to your instance

Connect over SSH on port 22 as the default login user for your operating system variant:

ssh -i /path/to/your-key.pem ubuntu@<public-ip>

Retrieve the per-instance UI password

The UI password is generated on the first boot of your instance and written to a root-only file. Read it with:

sudo cat /root/apache-skywalking-credentials.txt

You will see the generated password, the sign-in user (admin), and a note about the agent receiver ports:

SKYWALKING_URL=http://<public-ip>/
SKYWALKING_UI_USER=admin
SKYWALKING_UI_PASSWORD=xxxxxxxxxxxxxxxxxxxxxxxx

Confirm the services are running

systemctl is-active skywalking-banyandb skywalking-oap skywalking-ui nginx

All four report active:

active
active
active
active

The OAP JVM can take 30 to 60 seconds to finish starting on a cold boot; if a service is still activating, wait a moment and re-run the command.

Confirm the UI and its authentication

The nginx health endpoint answers without authentication, and the UI itself requires the per-instance password. On the instance:

curl -s http://127.0.0.1/health
curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1/

The health endpoint returns ok, and a request to the UI without credentials is rejected with 401:

ok
401

Sign in to the web UI

Open the SkyWalking web UI in your browser at http://<public-ip>/ (port 80). Your browser will prompt for HTTP basic authentication: sign in as admin with the password from the credentials file. The UI opens on the General service view, where service and endpoint metrics, the service topology and distributed traces are all available.

Send telemetry from your applications

To populate the UI you point SkyWalking agents at the instance. The OAP backend receives telemetry on gRPC port 11800 (used by most language agents) and HTTP port 12800. Open those ports to your own application or agent network range in the instance security group - not to the internet - then configure your agent. For the SkyWalking Java agent, for example:

java -javaagent:/path/to/skywalking-agent.jar \
  -Dskywalking.agent.service_name=my-service \
  -Dskywalking.collector.backend_service=<public-ip>:11800 \
  -jar my-application.jar

SkyWalking provides native agents for Java, .NET, Node.js, Python, Go, PHP and more, and also accepts OpenTelemetry and Zipkin data through the corresponding receivers.

Prove an end-to-end trace round-trip

You can confirm the full ingest, storage and query path without deploying an agent by posting a synthetic trace segment to the OAP native HTTP receiver and querying it back through the GraphQL API. On the instance:

SVC="demo-web-$(date +%s)"
NOW=$(($(date +%s)*1000))
printf '%s' "[{\"traceId\":\"demo.$(date +%s)\",\"traceSegmentId\":\"demoseg.$(date +%s)\",\"service\":\"$SVC\",\"serviceInstance\":\"$SVC-1\",\"spans\":[{\"operationName\":\"/checkout\",\"startTime\":$NOW,\"endTime\":$((NOW+42)),\"spanId\":0,\"parentSpanId\":-1,\"spanType\":\"Entry\",\"spanLayer\":\"Http\",\"componentId\":49,\"isError\":false,\"skipAnalysis\":false}]}]" > /tmp/seg.json
curl -s -o /dev/null -w 'ingest HTTP %{http_code}\n' -H 'Content-Type: application/json' -X POST http://127.0.0.1:12800/v3/segments -d @/tmp/seg.json
printf '%s' '{"query":"query{services:listServices(layer:\"GENERAL\"){name}}"}' > /tmp/q.json
for i in $(seq 1 20); do R=$(curl -s -H 'Content-Type: application/json' -d @/tmp/q.json http://127.0.0.1:12800/graphql); echo "$R" | grep -q "$SVC" && { echo "queried back: found $SVC"; break; }; sleep 3; done

The receiver accepts the segment (ingest HTTP 200), and within a few seconds the service is returned by the query API the UI uses:

ingest HTTP 200
queried back: found demo-web-1784939567

The synthetic service and its trace then appear in the web UI on the Service, Topology and Trace views.

Reaching the UI over an SSH tunnel

If you prefer not to open port 80, you can reach the UI over an SSH tunnel instead. Forward a local port to the nginx front end on the instance:

ssh -i /path/to/your-key.pem -L 8080:127.0.0.1:80 ubuntu@<public-ip>

Then browse http://127.0.0.1:8080/ on your workstation and sign in with the same admin credentials.

Storage, retention and the data volume

All SkyWalking telemetry is stored by Apache BanyanDB under /var/lib/skywalking/banyandb, on the dedicated EBS data volume. Because the data lives on its own volume you can resize it independently of the operating system disk, and you can snapshot it for backup. BanyanDB is bound to the loopback interface only and the OAP backend is its sole client.

To grow the datastore, expand the EBS volume in the AWS console, then extend the filesystem on the instance:

sudo resize2fs $(findmnt -no SOURCE /var/lib/skywalking)

Managing the services

The platform is managed with standard systemd commands:

sudo systemctl status skywalking-oap
sudo systemctl restart skywalking-ui
sudo journalctl -u skywalking-oap -n 100 --no-pager

BanyanDB (skywalking-banyandb) must be running before the OAP backend, and the OAP backend before the UI; systemd enforces this ordering automatically on boot.

Securing the UI with TLS

The nginx front end serves the UI over plain HTTP on port 80 with basic authentication. For production use, place the instance behind a TLS terminator - an AWS Application Load Balancer with an ACM certificate, or a certificate installed directly in nginx - so the UI password and telemetry queries are encrypted in transit. Do not expose the UI to the internet without TLS.

Backup and maintenance

• Back up the observability data by snapshotting the /var/lib/skywalking EBS volume on your own schedule
• Rotate the UI password by editing /etc/nginx/.htpasswd with sudo htpasswd /etc/nginx/.htpasswd admin and reloading nginx
• Apply OS updates with sudo apt-get update && sudo apt-get upgrade during a maintenance window, then reboot if a new kernel was installed

Support

Every deployment is backed by cloudimg engineers available around the clock by email and live chat. Support covers deployment and sizing guidance, agent instrumentation across languages, exposing the UI securely behind TLS and authentication, Apache BanyanDB storage management and retention, backup and restore of the data volume, and SkyWalking and JVM tuning and troubleshooting. Contact support@cloudimg.co.uk.

Apache, Apache SkyWalking and Apache BanyanDB are trademarks of The Apache Software Foundation.