This is an automated email from the ASF dual-hosted git repository. wusheng pushed a commit to branch docs/improve-documentation-structure in repository https://gitbox.apache.org/repos/asf/skywalking.git
commit 2845cda61d1c0c56a0315efb151b0f4450efc680 Author: Wu Sheng <[email protected]> AuthorDate: Fri Jan 16 14:31:11 2026 +0800 Improve documentation structure and navigation - Restructure docs/README.md for better high-level navigation - Move Marketplace as top-level menu section with Overview introduction - Polish marketplace.md as overview page for out-of-box monitoring features - Add "What's Next" section to Quick Start docs guiding users to Marketplace - Restructure agent compatibility page with OAP 10.x focus and clearer format - Add PR submission guidelines to CLAUDE.md Co-Authored-By: Claude Opus 4.5 <[email protected]> --- CLAUDE.md | 48 +++++++++++++++-- docs/README.md | 53 ++++++++++++++----- docs/en/changes/changes.md | 5 ++ docs/en/setup/backend/backend-docker.md | 3 ++ docs/en/setup/backend/backend-k8s.md | 3 ++ docs/en/setup/backend/backend-setup.md | 3 ++ docs/en/setup/backend/marketplace.md | 37 ++++++++++--- docs/en/setup/service-agent/agent-compatibility.md | 60 ++++++++++++++-------- docs/menu.yml | 4 +- 9 files changed, 170 insertions(+), 46 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 7ccc0dab15..599e4c49f3 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -260,14 +260,56 @@ Always use `--recurse-submodules` when cloning or update submodules manually. - `lal/` - Log processing rules - `log-mal-rules/` - Metrics extracted from logs -## Important Links +## Documentation (in `docs/en/`, structure defined in `docs/menu.yml`) + +- `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 + +## Community -- Documentation: `docs/en/` folder (source for all published docs, structure defined in `docs/menu.yml`) -- Change Logs: `docs/en/changes/changes.md` (update this file when making changes) - GitHub Issues: https://github.com/apache/skywalking/issues - Mailing List: [email protected] - Slack: #skywalking channel at Apache Slack +## Submitting Pull Requests + +### Branch Strategy +- **Never work directly on master branch** +- Create a new branch for your changes: `git checkout -b feature/your-feature-name` or `git checkout -b fix/your-fix-name` +- Keep branch names descriptive and concise + +### PR Title +Summarize the changes in the PR title. Examples: +- `Fix BanyanDB query timeout issue` +- `Add support for OpenTelemetry metrics` +- `Improve documentation structure` + +### PR Description +Follow the PR template in `.github/PULL_REQUEST_TEMPLATE`. Key requirements: + +**For Bug Fixes:** +- Add unit test to verify the fix +- Explain briefly why the bug exists and how to fix it + +**For New Features:** +- Link to design doc if non-trivial +- Update documentation +- Add tests (UT, IT, E2E) +- Attach screenshots if UI related + +**For Performance Improvements:** +- Add benchmark for the improvement +- Include benchmark results +- Link to theory proof or discussion articles + +**Always:** +- Reference related issue: `Closes #<issue number>` +- Update [`CHANGES` log](https://github.com/apache/skywalking/blob/master/docs/en/changes/changes.md) + ## Tips for AI Assistants 1. **Always check submodules**: Protocol changes may require submodule updates diff --git a/docs/README.md b/docs/README.md index 8c13e4d2bd..f0fa70fe2f 100644 --- a/docs/README.md +++ b/docs/README.md @@ -2,28 +2,53 @@ **This is the official documentation of SkyWalking 10. Welcome to the SkyWalking community!** -Here you can learn all you need to know about **SkyWalking**'s architecture, understand how to deploy and use SkyWalking, and contribute to the project based on SkyWalking's contributing guidelines. +SkyWalking is an open source observability platform for collecting, analyzing, aggregating, and visualizing data from services and cloud native infrastructures. It provides distributed tracing, service mesh telemetry analysis, metrics aggregation, alerting, and visualization capabilities. -- **Concepts and Designs**. You'll find the core logic behind SkyWalking. You may start from here if you want to - understand what is going on under our cool features and visualization. +## Documentation Structure -- **Setup**. A guide to install SkyWalking for different use cases. It is an observability platform that supports multiple observability modes. +### Concepts and Designs +Understand the core architecture, terminology, and design principles of SkyWalking. Start with the [Overview](en/concepts-and-designs/overview.md). -- **Contributing Guides**. If you are a PMC member, a committer, or a new contributor, learn how to start contributing with these guides! +### Setup +Installation and configuration guides for different deployment scenarios. -- **Protocols**. The protocols show how agents/probes and the backend communicate with one another. Anyone interested in uplinking telemetry data should definitely read this. +- **Quick Start** - Get SkyWalking running with [Docker](en/setup/backend/backend-docker.md) or [Kubernetes](en/setup/backend/backend-k8s.md) +- **Marketplace** - Explore all [out-of-box monitoring features](en/setup/backend/marketplace.md) for services, service mesh, Kubernetes, databases, message queues, and more +- **Agent Compatibility** - Check [supported libraries and frameworks](en/setup/service-agent/agent-compatibility.md) for SkyWalking language agents +- **Advanced Setup** - Storage options, cluster management, security, and dynamic configuration -- **FAQs**. A manifest of known issues with setup and secondary developments processes. Should you encounter any problems, check here first. +### APIs +Protocol specifications for integration, including [Telemetry APIs](en/api/trace-data-protocol-v3.md) for reporting data and [Query APIs](en/api/query-protocol.md) for retrieving data. -You might also find these links interesting: +### Customization +Extend SkyWalking with custom analysis pipelines using [Observability Analysis Language](en/concepts-and-designs/oal.md), [Meter Analysis Language](en/concepts-and-designs/mal.md), and [Log Analysis Language](en/concepts-and-designs/lal.md). -- The latest and old releases are all available - at [Apache SkyWalking release page](https://skywalking.apache.org/downloads/). The change logs can be - found [here](https://github.com/apache/skywalking/tree/master/changes). +### Security +[Suggestions](en/security/README.md) for keeping your SkyWalking deployment secure. For reporting security vulnerabilities, please follow the [ASF Security Policy](https://www.apache.org/security/). -- [SkyWalking WIKI](https://cwiki.apache.org/confluence/display/SKYWALKING/Home) hosts the context of some changes and events. +### Academy +In-depth [articles and papers](en/academy/scaling-with-apache-skywalking.md) about SkyWalking architecture and best practices. -- You can find the conference schedules, video recordings, and articles about SkyWalking in the [community resource catalog](https://github.com/OpenSkywalking/Community). +### FAQs +[Solutions](en/FAQ/README.md) to common issues with setup and development. -We're always looking for help to improve our documentation and codes, so please don’t hesitate to [file an issue](https://github.com/apache/skywalking/issues/new) if you see any problems. Or better yet, directly contribute by submitting a pull request to help us get better! +### Contributing Guides +For contributors and committers - [contact the community](en/guides/community.md), learn how to [build](en/guides/How-to-build.md) and [test](en/guides/e2e.md) the project. For major features, see [SkyWalking Improvement Proposals](en/swip/readme.md). +### Changelog +Release notes and version history. See [current version](en/changes/changes.md) or browse all versions in the documentation menu. + +## Additional Resources + +- [Apache SkyWalking Downloads](https://skywalking.apache.org/downloads/) - Official releases +- [SkyWalking WIKI](https://cwiki.apache.org/confluence/display/SKYWALKING/Home) - Additional context and events +- [Community Resources](https://github.com/OpenSkywalking/Community) - Conference schedules, videos, and articles +- [SkyWalking CLI](https://github.com/apache/skywalking-cli) - Command line interface + +## Getting Help + +- **Questions & Answers** - Post to [GitHub Discussions](https://github.com/apache/skywalking/discussions) +- **Bug Reports** - File an [issue](https://github.com/apache/skywalking/issues/new) directly if you're certain it's a bug +- **Slack Channels** - Join `#skywalking` for English or `#skywalking-cn` for Chinese discussions. To get an invite, send a request to [email protected] + +We're always looking for help to improve our documentation and code. Feel free to contribute by submitting a pull request! diff --git a/docs/en/changes/changes.md b/docs/en/changes/changes.md index b8db97022b..0acc435e42 100644 --- a/docs/en/changes/changes.md +++ b/docs/en/changes/changes.md @@ -35,6 +35,11 @@ * Add benchmark selection into banyanDB storage documentation. * Fix progressive TTL doc for banyanDB. +* Restructure `docs/README.md` for better navigation with high-level documentation overview. +* Move Marketplace as a top-level menu section with Overview introduction in `menu.yml`. +* Polish `marketplace.md` as the overview page for all out-of-box monitoring features. +* Add "What's Next" section to Quick Start docs guiding users to Marketplace. +* Restructure agent compatibility page with OAP 10.x focus and clearer format for legacy versions. All issues and pull requests are [here](https://github.com/apache/skywalking/issues?q=milestone:10.4.0) diff --git a/docs/en/setup/backend/backend-docker.md b/docs/en/setup/backend/backend-docker.md index 230daa01c2..99ed419093 100644 --- a/docs/en/setup/backend/backend-docker.md +++ b/docs/en/setup/backend/backend-docker.md @@ -48,3 +48,6 @@ The files with the same name will be overridden; otherwise, they will be added t If you want to add more libs/jars into the classpath of OAP, for example, new metrics for OAL. These jars can be mounted into `/skywalking/ext-libs`, then `entrypoint` bash will append them into the classpath. Notice, you can't override an existing jar in classpath. + +# What's Next +After setting up SkyWalking with Docker, explore the [Marketplace](marketplace.md) to discover all available monitoring features, including language agents, service mesh observability, infrastructure monitoring, and more. diff --git a/docs/en/setup/backend/backend-k8s.md b/docs/en/setup/backend/backend-k8s.md index a030f5add3..0c1e21a72d 100644 --- a/docs/en/setup/backend/backend-k8s.md +++ b/docs/en/setup/backend/backend-k8s.md @@ -7,3 +7,6 @@ Follow instructions in the [deploying SkyWalking backend to Kubernetes cluster]( to deploy OAP and UI to a Kubernetes cluster. Please refer to the Readme file. + +## What's Next +After deploying SkyWalking to Kubernetes, explore the [Marketplace](marketplace.md) to discover all available monitoring features, including language agents, service mesh observability, infrastructure monitoring, and more. diff --git a/docs/en/setup/backend/backend-setup.md b/docs/en/setup/backend/backend-setup.md index 38198e03f5..587b7ded1a 100755 --- a/docs/en/setup/backend/backend-setup.md +++ b/docs/en/setup/backend/backend-setup.md @@ -180,3 +180,6 @@ For example, metrics time will be formatted like yyyyMMddHHmm in minute dimensio By default, SkyWalking's OAP backend chooses the **OS default timezone**. Please follow the Java and OS documents if you want to override the timezone. +## What's Next +After setting up the backend, explore the [Marketplace](marketplace.md) to discover all available monitoring features, including language agents, service mesh observability, infrastructure monitoring, and more. + diff --git a/docs/en/setup/backend/marketplace.md b/docs/en/setup/backend/marketplace.md index 7a398b3397..874ff29b81 100644 --- a/docs/en/setup/backend/marketplace.md +++ b/docs/en/setup/backend/marketplace.md @@ -1,12 +1,35 @@ # Marketplace -**Marketplace** is the first UI menu on the SkyWalking native UI. +The **Marketplace** provides an overview of all out-of-box monitoring features available in SkyWalking. It is also the first UI menu on the SkyWalking native UI. -The native out-of-box features are listed in the marketplace. Follow the `Documentation` guidance to set up the required components. -Once SkyWalking detects the services of those layers, the relative menu will show up on the left automatically. +## Out-of-Box Monitoring Features -If you prefer to have a custom dashboard to visualize your metrics, logs, and traces in your private setup, you need to -1. Follow Tracing, Logging, and Metrics documentation to set up codes. -2. Follow Customization documentation to add analysis pipeline. -3. Follow [UI Customization Setup documentation](../../ui/README.md) to set up new UI dashboards. +SkyWalking provides ready-to-use monitoring capabilities for a wide range of technologies and platforms: + +- **General Services** - Application monitoring with language agents (Java, Python, Go, Node.js, PHP, .NET, etc.), including tracing, metrics, and profiling +- **Service Mesh** - Observability for Istio and Envoy-based service meshes through Access Log Service (ALS) or metrics +- **Kubernetes** - Cluster monitoring, pod metrics, and network profiling +- **Infrastructure** - Linux and Windows server monitoring +- **Cloud Services** - AWS EKS, S3, DynamoDB, API Gateway, and more +- **Gateways** - Nginx, APISIX, Kong monitoring +- **Databases** - MySQL, PostgreSQL, Redis, Elasticsearch, MongoDB, ClickHouse, and more +- **Message Queues** - Kafka, RabbitMQ, Pulsar, RocketMQ, ActiveMQ +- **Browser** - Real user monitoring for web applications +- **Self Observability** - Monitor SkyWalking OAP, Satellite, and agents themselves + +## How It Works + +1. Browse the Marketplace sections in this documentation to find your target technology +2. Follow the setup guide to configure the required agents, receivers, or integrations +3. Once SkyWalking detects services of the configured type, the corresponding menu and dashboards will appear automatically in the UI + +Each monitoring feature comes with pre-built dashboards, metrics, and alerting capabilities. + +## Advanced: Custom Dashboards + +For users who need to visualize custom metrics or create specialized dashboards beyond the out-of-box features: + +1. Set up data collection following the Tracing, Logging, or Metrics documentation +2. Configure custom analysis pipelines using the Customization documentation +3. Create custom UI dashboards following the [UI Customization documentation](../../ui/README.md) diff --git a/docs/en/setup/service-agent/agent-compatibility.md b/docs/en/setup/service-agent/agent-compatibility.md index 364d5eeb7a..fe743d24c3 100644 --- a/docs/en/setup/service-agent/agent-compatibility.md +++ b/docs/en/setup/service-agent/agent-compatibility.md @@ -1,32 +1,52 @@ # Compatibility -SkyWalking 8.0+ uses v3 protocols. Agents don't have to keep the identical versions as the OAP backend. +SkyWalking uses v3 protocols. Agents don't have to keep the identical versions as the OAP backend. + +**We recommend always using the latest releases of both OAP server and agents for better performance and advanced +features.** ## SkyWalking Native Agents -| OAP Server Version | Java | Python | NodeJS | LUA | Kong | Browser Agent | Rust | PHP | Go | Rover | Satellite | Ruby | -|--------------------|-------------------------|-----------|-----------|-----|------|---------------|------|-----|------------|------------|------------|------------| -| 8.0.1 - 8.1.0 | 8.0.0 - 8.3.0 | < = 0.6.0 | < = 0.3.0 | All | All | No | All | No | No | No | No | No | -| 8.2.0 - 8.3.0 | 8.0.0 - 8.3.0 | < = 0.6.0 | < = 0.3.0 | All | All | All | All | No | No | No | No | No | -| 8.4.0 - 8.8.1 | \> = 8.0.0 | All | All | All | All | All | All | All | No | No | No | No | -| 8.9.0+ | \> = 8.0.0 | All | All | All | All | All | All | All | No | No | \> = 0.4.0 | No | -| 9.0.0 | \> = 8.0.0 | All | All | All | All | All | All | All | No | No | \> = 0.4.0 | No | -| 9.1.0+ | \> = 8.0.0 | All | All | All | All | All | All | All | No | \> = 0.1.0 | \> = 1.0.0 | No | -| 9.5.0+ | \> = 8.0.0 & \> = 9.0.0 | All | All | All | All | All | All | All | \> = 0.1.0 | \> = 0.5.0 | \> = 1.2.0 | \> = 0.1.0 | +### OAP 10.x (Current) + +**Agents with specific version requirements:** + +| Agent | Minimum Version | +|-----------|-----------------| +| Java | 8.x, 9.x | +| Go | 0.1+ | +| Rover | 0.5+ | +| Satellite | 1.2+ | + +**Agents compatible with all versions:** +Python, NodeJS, PHP, Rust, Ruby, Browser, LUA, Kong + +### Legacy Versions (8.x - 9.x) + +For users on OAP 8.x or 9.x, refer to the table below. Note: these versions are no longer actively maintained. + +| OAP Server Version | Java | Python | NodeJS | Go | Rover | Satellite | Ruby | +|--------------------|-----------|--------|--------|------|-------|-----------|------| +| 9.5 - 9.7 | 8.x, 9.x | All | All | 0.1+ | 0.5+ | 1.2+ | 0.1+ | +| 9.1 - 9.4 | 8.x | All | All | No | 0.1+ | 1.0+ | No | +| 9.0 | 8.x | All | All | No | No | 0.4+ | No | +| 8.4 - 8.9 | 8.x | All | All | No | No | No | No | +| 8.0 - 8.3 | 8.0 - 8.3 | 0.6- | 0.3- | No | No | No | No | ## Ecosystem Agents -All following agent implementations are a part of the SkyWalking ecosystem. All the source codes and their distributions -don't belong to the Apache Software Foundation. +The following agent implementations are part of the SkyWalking ecosystem. Their source codes and distributions are +maintained by their respective communities and don't belong to the Apache Software Foundation. -| OAP Server Version | DotNet | cpp2sky | -|--------------------|---------------|-----------| -| 8.0.1 - 8.3.0 | 1.0.0 - 1.3.0 | < = 0.2.0 | -| 8.4.0+ | \> = 1.0.0 | All | -| 9.0.0+ | \> = 1.0.0 | All | +| OAP Server Version | DotNet | cpp2sky | +|--------------------|-----------|----------------| +| 10.x | 1.0+ | All | +| 9.x | 1.0+ | All | +| 8.4+ | 1.0+ | All | +| 8.0 - 8.3 | 1.0 - 1.3 | 0.2 or earlier | -All these projects are maintained by their own communities, and please reach them if you face any compatibility issues. +Please reach out to their respective communities if you face any compatibility issues. ___ -All above compatibility are only references, and if you face an `unimplemented` error, it means you need to upgrade the -OAP backend to support newer features in the agents. +The compatibility information above is for reference. If you encounter an `unimplemented` error, upgrade the OAP backend +to support newer features in the agents. diff --git a/docs/menu.yml b/docs/menu.yml index 9fdf89bdc9..adb2ee8936 100644 --- a/docs/menu.yml +++ b/docs/menu.yml @@ -44,10 +44,10 @@ catalog: path: "/en/setup/backend/backend-docker" - name: "Run with Kubernetes" path: "/en/setup/backend/backend-k8s" - - name: "Find out-of-box Features in Marketplace" - path: "/en/setup/backend/marketplace" - name: "Marketplace" catalog: + - name: "Overview" + path: "/en/setup/backend/marketplace" - name: "General Service" catalog: - name: "Server Agents"
