You are viewing a plain text version of this content. The canonical link for it is here.
Posted to notifications@skywalking.apache.org by "wu-sheng (via GitHub)" <gi...@apache.org> on 2026/01/15 12:42:20 UTC
[PR] Add CLAUDE.md file for AI assistant. [skywalking]
wu-sheng opened a new pull request, #13669:
URL: https://github.com/apache/skywalking/pull/13669
<!--
⚠️ Please make sure to read this template first, pull requests that don't accord with this template
maybe closed without notice.
Texts surrounded by `<` and `>` are meant to be replaced by you, e.g. <framework name>, <issue number>.
Put an `x` in the `[ ]` to mark the item as CHECKED. `[x]`
-->
<!-- ==== 🐛 Remove this line WHEN AND ONLY WHEN you're fixing a bug, follow the checklist 👇 ====
### Fix <bug description or the bug issue number or bug issue link>
- [ ] Add a unit test to verify that the fix works.
- [ ] Explain briefly why the bug exists and how to fix it.
==== 🐛 Remove this line WHEN AND ONLY WHEN you're fixing a bug, follow the checklist 👆 ==== -->
<!-- ==== 📈 Remove this line WHEN AND ONLY WHEN you're improving the performance, follow the checklist 👇 ====
### Improve the performance of <class or module or ...>
- [ ] Add a benchmark for the improvement, refer to [the existing ones](https://github.com/apache/skywalking/blob/master/apm-commons/apm-datacarrier/src/test/java/org/apache/skywalking/apm/commons/datacarrier/LinkedArrayBenchmark.java)
- [ ] The benchmark result.
```text
<Paste the benchmark results here>
```
- [ ] Links/URLs to the theory proof or discussion articles/blogs. <links/URLs here>
==== 📈 Remove this line WHEN AND ONLY WHEN you're improving the performance, follow the checklist 👆 ==== -->
<!-- ==== 🆕 Remove this line WHEN AND ONLY WHEN you're adding a new feature, follow the checklist 👇 ====
### <Feature description>
- [ ] If this is non-trivial feature, paste the links/URLs to the design doc.
- [ ] Update the documentation to include this new feature.
- [ ] Tests(including UT, IT, E2E) are added to verify the new feature.
- [ ] If it's UI related, attach the screenshots below.
==== 🆕 Remove this line WHEN AND ONLY WHEN you're adding a new feature, follow the checklist 👆 ==== -->
- [ ] If this pull request closes/resolves/fixes an existing issue, replace the issue number. Closes #<issue number>.
- [x] Update the [`CHANGES` log](https://github.com/apache/skywalking/blob/master/docs/en/changes/changes.md).
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@skywalking.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Add CLAUDE.md file for AI assistant. [skywalking]
Posted by "wu-sheng (via GitHub)" <gi...@apache.org>.
wu-sheng merged PR #13669:
URL: https://github.com/apache/skywalking/pull/13669
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@skywalking.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Add CLAUDE.md file for AI assistant. [skywalking]
Posted by "Copilot (via GitHub)" <gi...@apache.org>.
Copilot commented on code in PR #13669:
URL: https://github.com/apache/skywalking/pull/13669#discussion_r2694243988
##########
CLAUDE.md:
##########
@@ -0,0 +1,280 @@
+# CLAUDE.md - AI Assistant Guide for Apache SkyWalking
+
+This file provides guidance for AI assistants working with the Apache SkyWalking codebase.
+
+## Project Overview
+
+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
+
+```
+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, ES, etc.)
Review Comment:
The abbreviation 'ES' is inconsistent with how Elasticsearch is referenced elsewhere in the file and codebase. Line 248 uses the full name 'Elasticsearch', and the codebase predominantly uses 'Elasticsearch' (not 'ElasticSearch' which appears in some older docs). Consider using 'Elasticsearch' instead of 'ES' for clarity.
```suggestion
│ ├── server-storage-plugin/ # Storage implementations (BanyanDB, Elasticsearch, etc.)
```
##########
CLAUDE.md:
##########
@@ -0,0 +1,280 @@
+# CLAUDE.md - AI Assistant Guide for Apache SkyWalking
+
+This file provides guidance for AI assistants working with the Apache SkyWalking codebase.
+
+## Project Overview
+
+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
+
+```
+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, ES, 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
+│ ├── analyzer/ # Log and trace analyzers
+│ ├── ai-pipeline/ # AI/ML pipeline components
+│ └── exporter/ # Data export functionality
+├── 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
+```
+
+## Build System
+
+### Prerequisites
+- JDK 11, 17, or 21 (LTS versions)
+- Maven 3.6+
+- Git (with submodule support)
+
+### Common Build Commands
+
+```bash
+# Clone with submodules
+git clone --recurse-submodules https://github.com/apache/skywalking.git
+
+# Or initialize submodules after clone
+git submodule init && git submodule update
+
+# Full build (skip tests)
+./mvnw clean package -Dmaven.test.skip
+
+# Build backend only
+./mvnw package -Pbackend,dist
+# or: make build.backend
+
+# Build UI only
+./mvnw package -Pui,dist
+# or: make build.ui
+
+# Run tests
+./mvnw test
+
+# Run integration tests
+./mvnw integration-test
+
+# Build with all profiles
+./mvnw clean package -Pall -Dmaven.test.skip
+```
+
+### Maven Profiles
+- `backend` (default): Builds OAP server modules
+- `ui` (default): Builds web application
+- `dist` (default): Creates distribution packages
+- `all`: Builds everything including submodule initialization
+
+## Architecture & Key Concepts
+
+### Module System
+SkyWalking uses a custom module/provider architecture based on Java SPI:
+
+- **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:
+```java
+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
+- **OAL (Observability Analysis Language)**: DSL for defining metrics aggregation rules
+- **MQE (Metrics Query Engine)**: DSL for querying metrics
+- **LAL (Log Analysis Language)**: DSL for log processing
+- **MAL (Meter Analysis Language)**: DSL for meter data processing
+- **Source/Scope**: Data model definitions for telemetry data
+- **Stream Processing**: Metrics, Records, and TopN processing pipelines
+
+### Data Flow
+1. Agents/Collectors send data via gRPC/HTTP/Kafka
+2. Receiver plugins parse and validate data
+3. Analysis engine processes data using OAL/LAL/MAL
+4. Storage plugins persist aggregated data
+5. Query plugins serve data to UI/API
+
+## Code Style & Conventions
+
+### Checkstyle Rules (enforced via `apm-checkstyle/checkStyle.xml`)
+
+**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)
+
+**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
+Java, XML, and YAML/YML files must include the Apache 2.0 license header (see `HEADER` file).
+JSON and Markdown files are excluded (JSON doesn't support comments, see `.licenserc.yaml`).
+
+## Testing
+
+### Test Frameworks
+- JUnit 5 (`org.junit.jupiter`)
+- Mockito for mocking
+- AssertJ for assertions
+- PowerMock for reflection utilities
+
+### Test Naming
+- Unit tests: `*Test.java`
+- Integration tests: `IT*.java` or `*IT.java`
+
+### Running Tests
+```bash
+# Unit tests only
+./mvnw test
+
+# Integration tests
+./mvnw integration-test
+
+# Skip tests during build
+./mvnw package -Dmaven.test.skip
+```
+
+## Git Submodules
+
+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.
+
+## IDE Setup (IntelliJ IDEA)
+
+1. Import as Maven project
+2. Run `./mvnw compile -Dmaven.test.skip=true` to generate protobuf sources
+3. Mark generated source folders:
+ - `*/target/generated-sources/protobuf/java`
+ - `*/target/generated-sources/protobuf/grpc-java`
+ - `*/target/generated-sources/antlr4`
+4. Import `codeStyle.xml` for consistent formatting
+
+## Key Files for Understanding the Codebase
+
+- `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
+
+### Adding a New Receiver Plugin
+1. Create module in `server-receiver-plugin/`
+2. Implement `ModuleDefine` and `ModuleProvider`
+3. Register via SPI in `META-INF/services/`
+4. Add configuration to `application.yml`
+
+### Adding a New Storage Plugin
+1. Create module in `server-storage-plugin/`
+2. Implement storage DAOs for each data type
+3. Follow existing plugin patterns (e.g., BanyanDB, Elasticsearch)
Review Comment:
The codebase uses both 'Elasticsearch' and 'ElasticSearch' inconsistently across documentation, but the official product name and the storage directory name is 'elasticsearch' (lowercase). While 'Elasticsearch' is correct here, it's worth noting the project has mixed usage. The actual directory is 'storage-elasticsearch-plugin'.
```suggestion
3. Follow existing plugin patterns (e.g., BanyanDB, elasticsearch)
```
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@skywalking.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org