Repository: apache/skywalking

Stars: 24782

CLAUDE.md Copy Chapter

CLAUDE.md - AI Assistant Guide for Apache SkyWalking

This file provides guidance for AI assistants working with the Apache SkyWalking codebase.

Project Overview Copy Chapter

Apache SkyWalking is an open-source APM (Application Performance Monitoring) system designed for microservices, cloud-native, and container-based architectures. It provides distributed tracing, service mesh telemetry analysis, metrics aggregation, alerting, and observability capabilities.

Repository Structure Copy Chapter

skywalking/
├── oap-server/                    # OAP (Observability Analysis Platform) backend server
│   ├── server-core/               # Core module with fundamental services
│   ├── server-library/            # Shared libraries (module system, util, etc.)
│   ├── server-receiver-plugin/    # Data receivers (gRPC, HTTP, Kafka, etc.)
│   ├── server-storage-plugin/     # Storage implementations (BanyanDB, Elasticsearch, etc.)
│   ├── server-cluster-plugin/     # Cluster coordination (Zookeeper, K8s, etc.)
│   ├── server-query-plugin/       # Query interfaces (GraphQL)
│   ├── server-alarm-plugin/       # Alerting system
│   ├── server-fetcher-plugin/     # Data fetchers
│   ├── server-configuration/      # Dynamic configuration providers
│   ├── oal-grammar/               # OAL (Observability Analysis Language) grammar
│   ├── oal-rt/                    # OAL runtime
│   ├── mqe-grammar/               # MQE (Metrics Query Engine) grammar
│   ├── mqe-rt/                    # MQE runtime
│   ├── server-testing/             # Shared test utilities (DSL test framework)
│   ├── analyzer/                  # Log and trace analyzers
│   ├── ai-pipeline/               # AI/ML pipeline components
│   ├── exporter/                  # Data export functionality
│   └── server-tools/              # Standalone tools (profile exporter) with mock providers
├── apm-protocol/                  # Protocol definitions (submodule)
│   └── apm-network/               # gRPC/Protobuf network protocols
├── skywalking-ui/                 # Web UI (submodule - skywalking-booster-ui)
├── apm-webapp/                    # Web application packaging
├── apm-dist/                      # Distribution packaging
├── docs/                          # Documentation
├── docker/                        # Docker build files
├── test/                          # E2E and integration tests
└── tools/                         # Development tools

Architecture & Key Concepts Copy Chapter

Module System Copy Section

- ModuleDefine: Declares a module and its required services
- ModuleProvider: Implements a module with specific technology/approach
- Service: Interface that modules expose to other modules

Key pattern:

public class XxxModule extends ModuleDefine {
    public Class[] services() {
        return new Class[] { XxxService.class };
    }
}
public class XxxModuleProvider extends ModuleProvider {
    public void prepare() { / initialize / }
    public void start() { / start services / }
}

Core Concepts Copy Section

Data Flow Copy Section

Code Style & Conventions Copy Chapter

Checkstyle Rules (enforced via apm-checkstyle/checkStyle.xml) apm-checkstyle/checkStyle.xml)')" title="Copy section prompt for LLMs"> Copy Section

Prohibited patterns:
- No System.out.println - use proper logging (SLF4J)
- No @author tags - ASF projects don't use author annotations
- No Chinese characters in source files
- No tab characters (use 4 spaces)
- No star imports (import xxx.*)
- No unused or redundant imports
- No empty statements (standalone ;)

Required patterns:
- @Override annotation required for overridden methods
- equals() and hashCode() must be overridden together
- Javadoc @param, @return, @throws must have descriptions
- Long constants must use uppercase L (e.g., 100L not 100l)
- default case must come last in switch statements
- One statement per line

Naming conventions:
- Constants/static variables: UPPER_CASE_WITH_UNDERSCORES
- Type parameters: UPPER_CASE (e.g., TYPE, KEY, VALUE)
- Package names: org.apache.skywalking. or test.apache.skywalking.
- Type names: PascalCase or UPPER_CASE_WITH_UNDERSCORES
- Local variables/parameters/members: camelCase

File limits:
- Max file length: 3000 lines

Whitespace:
- Whitespace required after commas, semicolons, type casts
- Whitespace required around operators
- No multiple consecutive blank lines
- Empty line separators between class members (fields can be grouped)

Code Style (via codeStyle.xml for IntelliJ IDEA) codeStyle.xml for IntelliJ IDEA)')" title="Copy section prompt for LLMs"> Copy Section

Indentation:
- 4-space indentation
- 4-space continuation indent

Imports:
- No star imports (threshold set to 999)
- Import order: regular imports, blank line, static imports

Formatting:
- while in do-while on new line
- Align multiline chained method calls
- Align multiline parameters in calls
- Array initializer braces on new lines
- Wrap long method call chains

General:
- Use final for local variables and parameters
- Use Lombok annotations (@Getter, @Setter, @Builder, @Data, @Slf4j, etc.)
- Follow existing patterns in similar files

License Header Copy Section

JDK 11 Compatibility Copy Section

All code must be compatible with JDK 11 (LTS). The project supports JDK 11, 17, and 21.

Prohibited Java features (post-JDK 11):

| Feature | JDK Version | Use Instead |
|---------|-------------|-------------|
| Switch expressions (->) | 14+ | Traditional switch with case: and break |
| Stream.toList() | 16+ | .collect(Collectors.toList()) |
| Text blocks ("""...""") | 15+ | String concatenation or + |
| Records | 14+ | Regular classes with Lombok @Data |
| Pattern matching for instanceof | 14+ | Traditional cast after instanceof |
| Sealed classes/interfaces | 15+ | Regular classes/interfaces |

Allowed Java features (JDK 11 compatible):
- List.of(), Set.of(), Map.of() - Immutable collections (Java 9+)
- Optional methods - orElseThrow(), ifPresentOrElse() (Java 9+)
- Lambda expressions and method references (Java 8+)
- Stream API (Java 8+)
- Lombok annotations (@Getter, @Builder, @Data, @Slf4j)

Verification commands:

Check for switch expressions (should return no matches)

grep -r "switch.->" src/ --include=".java"
Check for Stream.toList() (should return no matches)

grep -r "\.toList()" src/ --include="*.java"
Check for text blocks (should return no matches)

grep -r '"""' src/ --include="*.java"

Git Submodules Copy Chapter

The project uses submodules for protocol definitions and UI:
- apm-protocol/apm-network/src/main/proto - skywalking-data-collect-protocol
- oap-server/server-query-plugin/.../query-protocol - skywalking-query-protocol
- skywalking-ui - skywalking-booster-ui
- oap-server/server-library/library-banyandb-client/src/main/proto - banyandb-client-proto

Always use --recurse-submodules when cloning or update submodules manually.

Key Files for Understanding the Codebase Copy Chapter

- oap-server/server-core/src/main/java/.../CoreModule.java - Core module definition
- oap-server/server-library/library-module/src/main/java/.../ModuleDefine.java - Module system base
- oap-server/oal-grammar/src/main/antlr4/.../OALParser.g4 - OAL grammar definition
- oap-server/server-starter/ - Application entry point
- docs/en/concepts-and-designs/ - Architecture documentation

Common Development Tasks Copy Chapter

Adding a New Receiver Plugin Copy Section

Adding a New Storage Plugin Copy Section

Modifying OAL Metrics Copy Section

MAL Scripts (in oap-server/server-starter/src/main/resources/) oap-server/server-starter/src/main/resources/)')" title="Copy section prompt for LLMs"> Copy Section

LAL Scripts (in oap-server/server-starter/src/main/resources/) oap-server/server-starter/src/main/resources/)')" title="Copy section prompt for LLMs"> Copy Section

Documentation (in docs/en/, structure defined in docs/menu.yml) docs/en/, structure defined in docs/menu.yml)')" title="Copy chapter prompt for LLMs"> Copy Chapter

- concepts-and-designs/ - Architecture and core concepts (OAL, MAL, LAL, profiling)
- setup/ - Installation and configuration guides
- api/ - Telemetry and query protocol documentation
- guides/ - Contributing guides, build instructions, testing
- changes/changes.md - Changelog (update when making changes)
- swip/ - SkyWalking Improvement Proposals

Submitting Pull Requests Copy Chapter

Use the /gh-pull-request skill for committing and pushing to a PR branch. It runs pre-flight checks (compile, checkstyle, license headers) before every push, and creates the PR if one doesn't exist yet.

GitHub Actions Allow List Copy Chapter

Apache enforces an allow list for third-party GitHub Actions. All third-party actions must be pinned to an approved SHA from:
https://github.com/apache/infrastructure-actions/blob/main/approved_patterns.yml

If a PR is blocked by "action is not allowed" errors, check the approved list and update .github/workflows/ files to use the approved SHA pin instead of a version tag.

Actions owned by actions/ (GitHub), github/, and apache/* are always allowed (enterprise-owned).

Tips for AI Assistants Copy Chapter

1. Always check submodules: Protocol changes may require submodule updates
2. Generate sources first: Run mvnw compile before analyzing generated code
3. Install package: Use mvnw flatten:flatten install to build the precompiler and export generated classes before running tests. ref to compile skill doc
3. Respect checkstyle: No System.out, no @author, no Chinese characters
4. Follow module patterns: Use existing modules as templates
5. Check multiple storage implementations: Logic may vary by storage type
6. OAL generates code: Don't manually edit generated metrics classes
7. Use Lombok: Prefer annotations over boilerplate code
8. Test both unit and integration: Different test patterns for different scopes
9. Documentation is rendered via markdown: When reviewing docs, consider how they will be rendered by a markdown engine
10. Relative paths in docs are valid: Relative file paths (e.g., ../../../oap-server/...) in documentation work both in the repo and on the documentation website, supported by website build tooling
11. Module service registration: When adding a service to CoreModule.services(), update ALL CoreModuleProvider implementations — not just the main one. Search with grep -rn "extends CoreModuleProvider" oap-server/ --include="*.java". The MockCoreModuleProvider in server-tools/profile-exporter/ also needs it, or the profile exporter e2e test will fail at startup.
12. Multiple OAP packagings: The OAP server is not only the main server-starter. The server-tools/ directory contains standalone tools (e.g., profile exporter) that boot with mock module providers and a subset of modules. Changes to core module contracts (services, required modules) must be reflected in these tools too.

Analysis and Design Principles Copy Chapter

Never guess or speculate. All analysis must be grounded in source code, documentation, or verified behavior.

Before making claims Copy Section

Before proposing changes Copy Section

When uncertain Copy Section

Docker images Copy Section

README.md Copy Chapter

Apache SkyWalking
==========

<img src="http://skywalking.apache.org/assets/logo.svg" alt="Sky Walking logo" height="90px" align="right" />

SkyWalking: an APM (Application Performance Monitoring) system, especially designed for
microservices, cloud native and container-based architectures.


!GitHub Release

Abstract

* Distributed Tracing
* End-to-end distributed tracing. Service topology analysis, service-centric observability and APIs dashboards.
* Agents for your stack
* Java, .Net Core, PHP, NodeJS, Golang, LUA, Rust, C++, Client JavaScript and Python agents with active development and maintenance.
* eBPF early adoption
* Rover agent works as a monitor and profiler powered by eBPF to monitor Kubernetes deployments and diagnose CPU and network performance.
* Scaling
* 100+ billion telemetry data could be collected and analyzed from one SkyWalking cluster.
* Mature Telemetry Ecosystems Supported
* Metrics, Traces, and Logs from mature ecosystems are supported, e.g. Zipkin, OpenTelemetry, Prometheus, Zabbix, Fluentd
* Native APM Database
* BanyanDB, an observability database, created in 2022, aims to ingest, analyze and store telemetry/observability data.
* Consistent Metrics Aggregation
* SkyWalking native meter format and widely known metrics format(OpenTelemetry, Telegraf, Zabbix, e.g.) are processed through the same script pipeline.
* Log Management Pipeline
* Support log formatting, extract metrics, various sampling policies through script pipeline in high performance.
* Alerting and Telemetry Pipelines
* Support service-centric, deployment-centric, API-centric alarm rule setting. Support forwarding alarms and all telemetry data to 3rd party.
* AI Power Enabled
* Machine Learning (ML) and Artificial Intelligence (AI) analyze observability data to identify patterns and enhance capabilities, such as recognizing HTTP URI patterns and automatically calculating metric baselines for intelligent alerting, improving anomaly detection.

<img src="https://skywalking.apache.org/images/home/architecture.svg?t=20220516"/>

Live Demo

Documentation

Downloads

Compiling project

Code of conduct

Contact Us

Our Users

License