# Apache SkyWalking

> Application performance monitoring and observability for distributed systems.

- Category: Monitoring & Observability
- Difficulty: intermediate
- Components: skywalking-oap, skywalking-ui, elasticsearch
- Tags: skywalking, apm, tracing, metrics, java
- Source: https://docker.recipes/monitoring/skywalking

## Overview

Apache SkyWalking OAP (Observability Analysis Platform) is the core backend component of the Apache SkyWalking APM system, designed to collect, analyze, and store observability data from distributed applications. Originally developed by Huawei and donated to the Apache Foundation in 2017, SkyWalking provides comprehensive application performance monitoring through distributed tracing, metrics collection, and topology analysis. The OAP server processes telemetry data from various language agents and presents it through advanced analytics and alerting capabilities.

This stack combines the SkyWalking OAP server with Elasticsearch for scalable data storage and the SkyWalking UI for visualization. Elasticsearch handles the high-volume ingestion of trace data, metrics, and logs, while the OAP server performs real-time analysis including service topology discovery, performance metric calculation, and alarm detection. The UI component provides interactive dashboards for exploring service maps, analyzing trace details, and monitoring application health across your entire distributed system.

Development teams managing microservices architectures, DevOps engineers implementing observability strategies, and operations teams troubleshooting performance issues will find this stack invaluable. Unlike simple logging solutions, SkyWalking provides automatic service dependency mapping, code-level performance insights, and correlation between infrastructure metrics and application behavior, making it particularly powerful for Java-heavy environments and complex distributed systems.

## Features

- Automatic service topology discovery and visualization without manual configuration
- Distributed tracing with context propagation across microservices boundaries
- Real-time performance metrics aggregation and statistical analysis
- Code-level profiling with method-level performance breakdown
- Multi-dimensional alarm system with customizable threshold rules
- Support for multiple programming languages through native agents
- Service mesh observability with Istio and Envoy integration
- Database performance monitoring with slow query detection

## Use cases

- Microservices performance monitoring in Spring Boot and Spring Cloud applications
- Root cause analysis for latency spikes in distributed e-commerce platforms
- Service dependency mapping during legacy system modernization projects
- API gateway performance optimization and bottleneck identification
- Database query performance analysis in multi-tenant SaaS applications
- Cross-team collaboration on service reliability in enterprise environments
- Compliance monitoring for SLA adherence in financial services applications

## Prerequisites

- Minimum 4GB RAM available (2GB for Elasticsearch, 1GB for OAP server)
- Ports 8080, 11800, and 12800 available on the host system
- Understanding of distributed tracing concepts and APM terminology
- Knowledge of your application's technology stack for agent installation
- Basic familiarity with Elasticsearch concepts for advanced configuration
- Access to application source code or deployment pipeline for agent integration

## docker-compose.yml

```yaml
services:
  elasticsearch:
    image: elasticsearch:7.17.9
    container_name: skywalking-es
    environment:
      discovery.type: single-node
      ES_JAVA_OPTS: "-Xms512m -Xmx512m"
    volumes:
      - es_data:/usr/share/elasticsearch/data
    networks:
      - skywalking-network

  skywalking-oap:
    image: apache/skywalking-oap-server:latest
    container_name: skywalking-oap
    restart: unless-stopped
    environment:
      SW_STORAGE: elasticsearch
      SW_STORAGE_ES_CLUSTER_NODES: elasticsearch:9200
    ports:
      - "11800:11800"
      - "12800:12800"
    depends_on:
      - elasticsearch
    networks:
      - skywalking-network

  skywalking-ui:
    image: apache/skywalking-ui:latest
    container_name: skywalking-ui
    restart: unless-stopped
    environment:
      SW_OAP_ADDRESS: http://skywalking-oap:12800
    ports:
      - "8080:8080"
    depends_on:
      - skywalking-oap
    networks:
      - skywalking-network

volumes:
  es_data:

networks:
  skywalking-network:
    driver: bridge
```

## .env

```bash
# SkyWalking configuration
```

## Usage notes

- Docs: https://skywalking.apache.org/docs/
- Dashboard at http://localhost:8080 - topology, traces, metrics
- Agent gRPC endpoint on port 11800 for language agents
- REST API on port 12800 for queries and integrations
- Install Java agent: -javaagent:skywalking-agent.jar
- Agents available for Java, .NET, Node.js, Python, Go, and more

## Troubleshooting

- OAP server fails to connect to Elasticsearch: Ensure Elasticsearch is fully started before OAP initialization and check network connectivity between containers
- No trace data appearing in UI: Verify application agents are properly configured with correct OAP server address (skywalking-oap:11800) and service names
- High memory usage in Elasticsearch: Adjust ES_JAVA_OPTS heap size settings and implement index lifecycle policies for data retention
- UI shows 'OAP server connection failed': Check that OAP server port 12800 is accessible and SW_OAP_ADDRESS environment variable is correctly set
- Agent connection refused errors: Ensure port 11800 is properly exposed and no firewall rules are blocking gRPC communication
- Missing service topology connections: Verify that trace context headers are properly propagated between services and agents support your communication protocols

