Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs:fix language issues in document #258

Merged
merged 3 commits into from
Jun 22, 2022
Merged

docs:fix language issues in document #258

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
dcb9325
docs:fix language issues in document
blue-troy Jun 21, 2022
30355f5
fix other issues found in the docs
Jun 22, 2022
545408c
docs:fix language issues in document
blue-troy Jun 22, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
51 changes: 26 additions & 25 deletions CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,59 +1,60 @@
# Contributing to kindling
Thank you for you interest in contributing to kindling! We welcome all people who want to contribute in a healthy and constructive manner within our community.
# Contributing to Kindling
Thank you for your interest in contributing to Kindling! We welcome all people who want to contribute in a healthy and constructive manner within our community.
​

## **Become a contributor**
you can contribute to Kindling in serveral ways,like:
l Contribute to the codebase
l Report and traige bugs
l Write technical documentation and blog posts, for users and contributors
l Help others by answering questions about Kindling
For more ways to contribute, check out the [Open Source Guides](https://opensource.guide/how-to-contribute/)
## Become a contributor
You can contribute to Kindling in several ways, like:
- Contribute to the codebase
- Report and triage bugs
- Write technical documentation and blog posts for users and contributors
- Help others by answering questions about Kindling

For more ways to contribute, check out the [Open Source Guides](https://opensource.guide/how-to-contribute/).
​

## **Report bugs**
## Report bugs
Before submitting a new issue, try to make sure someone hasn’t already reported the problem. You can look through the existing issues for similar issues.
​

[Report a bug](https://github.com/Kindling-project/kindling/issues/new?assignees=&labels=&template=bug_report.md&title=) by submitting a new issue. Make sure follow the issue template and add more detail informations that will help us replicate the problem.
[Report a bug](https://github.com/Kindling-project/kindling/issues/new?assignees=&labels=&template=bug_report.md&title=) by submitting a new issue. Make sure to follow the issue template and add more detailed information which will help us reproduce the problem.

## **Triage issues**
## Triage issues
If you don't have the knowledge or time to code, consider helping with issue triage. The community will thank you for saving them time by spending some of yours.
Read more about the ways you can [Triage issues](contribute/triage_issues.md).

## **Answering questions**
It's important to us to help these users who has problem about kindlings, and we’d love you help. Go to [disscussions](https://github.com/Kindling-project/kindling/discussions), you can find unanswered questions and you can answer thoes questions.
## Answering questions
It's important to us to help the users who have problems with Kindling, and we’d love your help. Go to [disscussions](https://github.com/Kindling-project/kindling/discussions), you can find unanswered questions, and you can answer those questions.


## **You first contribution**
The first step to getting starting contribute to kindling is to find something to work on. You can start by fixing biginner-fridendly issues or improving kindling documents ,no contribution is too small!
## Your first contribution
The first step to starting to contribute to Kindling is finding something to work on. You can start by fixing beginner-friendly issues or improving Kindling documents, no contribution is too small!

+ How to find biginner-friendly issues？Kindling has good first issue label for issues that don’t need high-level knowledge to contribute to. You can browser issues labeled good first time.
+ How to find beginner-friendly issues? Kindling has a `good first issue` label for issues that don’t need high-level knowledge to contribute. You can browse issues labeled with `good first time`.

+ How to find documents improving issues? Kindling has doc improvement label for issues that you can improve kinding docs.
+ How to find documents improving issues? Kindling has a `documentation` label for issues that you can improve Kindling docs.

If you are ready to contribute code changes, review the [developer guide](http://www.kindling.space:33215/project-1/doc-10/) for how to set up local environment.
When you want to submit your local changes , read about [create pull request](contribute/create_pull_request.md).
If you are ready to contribute code changes, review the [developer guide](http://www.kindling.space:33215/project-1/doc-10/) for how to set up your local environment.
When you want to submit your local changes, read about [create pull request](contribute/create_pull_request.md).

## Sign your commits

The sign-off is a simple line at the end of the explanation for a commit. All commits needs to be signed. Your signature certifies that you wrote the patch or otherwise have the right to contribute the material. The rules are pretty simple, if you can certify the rules (from [developercertificate.org](https://developercertificate.org/)),then you just need add a line to every git commit message, like:
The sign-off is a simple line at the end of the explanation for a commit. All commits need to be signed. Your signature certifies that you wrote the patch or otherwise have the right to contribute the material. The rules are pretty simple, if you can certify the rules (from [developercertificate.org](https://developercertificate.org/)), then you just need to add a line to every git commit message, like:

```
Signed-off-by: lina <lina@example.cn>
```

### configuring automation commit signing in git
### Configure auto commit signing in git

1) set your user.name and user.email using following commands:
1. Set your `user.name` and `user.email` using the following commands:

```
git config --global user.name lina

git config --global user.email lina@example.cn
git config --global user.email lina@example.cn
```

2. sign your commit with git commit -s, then use`git log `to verify that the signed-off message is added.
2. Sign your commit with `git commit -s`, then use `git log` to verify that the signed-off message is added.

```
Author: lina <lina@example.cn>
Expand Down
32 changes: 16 additions & 16 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,45 +8,45 @@ Visit [Kindling website](http://kindling.harmonycloud.cn/) for more information.

## What is Kindling

Kindling is an eBPF-based cloud-native monitor tool, which aims to help users understand the app behavior from kernel to code stack. Currently, it provides an easy way to get the view of the network flows in the Kubernetes environment, and many built-in network monitor dashboards like retransmit, DNS, throughput, TPS. Not only as a network monitor, but Kindling is also trying to analyze one detail RPC call and get the following information, which can be found in network explore in chrome. And the usage is the same as network explore in chrome, with which user can tell which part to dig into to find the root cause of the problem in the production environment.
Kindling is an eBPF-based cloud-native monitor tool, which aims to help users understand the app behavior from kernel to code stack. Currently, it provides an easy way to get the view of the network flows in the Kubernetes environment, and many built-in network monitor dashboards like retransmit, DNS, throughput, and TPS. Not only as a network monitor, but Kindling is also trying to analyze one detail RPC call and get the following information, which can be found in network explore in chrome. And the usage is the same as network explore in chrome, with which user can tell which part to dig into to find the root cause of the problem in the production environment.

![img](https://cdn.nlark.com/yuque/0/2021/png/749988/1633767195234-af2913c4-75d7-447d-99bb-bd1d815883ae.png)

# Architecture

From a high-level view, the agent runs as DeamonSet in Kuberntes. It collects all the SYSCALL and some other tracepoints. We use different exporters for different distributions. For the lightweight version, we just build a Prometheus exporter to export the data which can be stored into Prometheus and displayed in Grafana Plugin. For the standard version, which is designed for heavy usage, Kafka is adopted for buffering the events, and data is stored into ElasticSearch with much more detailed information which can be displayed. Currently, the light version has been open-sourced.
From a high-level view, the agent runs as DeamonSet in Kubernetes. It collects all the SYSCALL and some other tracepoints. We use different exporters for different distributions. For the lightweight version, we just build a Prometheus exporter to export the data which can be stored into Prometheus and displayed in Grafana Plugin. For the standard version, which is designed for heavy usage, Kafka is adopted for buffering the events, and data is stored into ElasticSearch with much more detailed information which can be displayed. Currently, the light version has been open-sourced.

![image.png](https://cdn.nlark.com/yuque/0/2022/png/2307576/1649841732151-7cf95801-940e-4e09-86c5-3cac147554fc.png?x-oss-process=image/format,png)

## Linux kernel version support

Kindling eBPF module depends on the kernel version which is larger than 4.14. As an eBPF constraint, the eBPF module can't work for older kernel version. But for the users who want to try the functionality with the old kernel, we use some module from Sysdig open-source project with enhancement and verification. Basically, the idea is to use a kernel module for tracking the kernel trace-point. Thanks to Sysdig open-source project, it provides a trace-point instrument framework for older kernel version.
Kindling eBPF module depends on the kernel version which is larger than 4.14. As an eBPF constraint, the eBPF module can't work for older kernel versions. But for the users who want to try the functionality with the old kernel, we use some modules from Sysdig open-source project with enhancement and verification. Basically, the idea is to use a kernel module for tracking the kernel trace-point. Thanks to Sysdig open-source project, which provides a trace-point instrument framework for older kernel versions.

For now, the kernel module works as expected as eBPF module during our test, but it is recommended to use eBPF module for production environment because it is safer than kernel module. In order to help old kernel version user experience the eBPF magic, we will support the kernel model. And you are welcome to report the issue for the kernel module. For the functionality, the kernel module and eBPF module capture the same data, and behave exactly the same.
For now, the kernel module works as expected as the eBPF module during our test, but it is recommended to use the eBPF module for the production environment because it is safer than the kernel module. In order to help users that are using old kernel versions experience the eBPF magic, we will support the kernel model. And you are welcome to report the issue for the kernel module. For the functionality, the kernel module and eBPF module capture the same data and behave exactly the same.

## Why we build Kindling?
## Why do we build Kindling?

When we talk about observability, we already have plenty of tools to use, like Skywalking for tracing, ELK for logging, Prometheus for metric. Why should we build an eBPF-based monitor tool?
When we talk about observability, we already have plenty of tools to use, like Skywalking for tracing, ELK for logging, and Prometheus for metric. Why should we build an eBPF-based monitor tool?

The majority issue for user adoption of k8s is the complexity. For the apps on the kubernetes, we don't know the network flows between the service until we can instrument the apps. We can't tell which part to blame when there is a product issue arise. Do we configure the kubernetes correctly? Are there any bugs in the virtual network like Calico/Flannel that caused this problem? Does the app code cause this issue?
The majority issue for user adoption of k8s is the complexity. For the apps on the Kubernetes, we don't know the network flows between the service until we can instrument the apps. We can't tell which part to blame when there is a product issue arise. Do we configure the Kubernetes correctly? Are there any bugs in the virtual network like Calico/Flannel that caused this problem? Does the app code cause this issue?

We are a company based in Hangzhou, China and used to provide the kubernetes distribution for our customers. Our customers used to have those questions, and we don't have a proper solution to answer those questions.
We are a company based in Hangzhou, China, and used to provide Kubernetes distribution for our customers. Our customers used to have those questions, and we don't have a proper solution to answer those questions.

APM is good for those java language apps which can be instrumented automatically, but the code has to be rewritten for instrumenting the go apps. And even we adopt the APM solution, we still can't tell whether an issue is caused by network problems.

We found it may be helpful that we check the issue from the network view to identify issues roughly like "oh, it's a network problem, the code works fine, we should dig into the configuration of calico" or "the infrastructure works fine, the app code should be blamed, let's dig into the logs or the APM dashboard for further information"

### Why eBPF
### Why eBPF?

Libpcap way of analyzing the flows in the kubernetes environment is too expensive for CPU and network. eBPF way of data capture cost much less than libpcap. eBPF is the most popular technology to track the Linux kernel. And the virtual network is built by veth-pair and iptables, which works in the kernel. So eBPF should be used for tracking how the kernel respond to the app request.
The libpcap way of analyzing the flows in the Kubernetes environment is too expensive for CPU and network. eBPF way of data capture cost much less than libpcap. eBPF is the most popular technology to track the Linux kernel. And the virtual network is built by veth-pair and iptables, which works in the kernel. So eBPF should be used for tracking how the kernel responds to the app request.

## Core Features

![img](https://cdn.nlark.com/yuque/0/2022/png/749988/1642572876088-c26396ac-e7bb-44e7-ae0c-cc96f3344cd8.png)

Kindling provides two versions which has different feature but with the same agent. The lightweight is integrated into Prometheus, and it uses PromQL to query the data from Prometheus, so it should be adopted easily. But due to the cardinality constraint of Prometheus, we group the detailed data into buckets which throw away the detailed information. For the standard version, we provide much more detailed information because we use ElasticSearch as the back-end to store the original information.
Kindling provides two versions that have different features but with the same agent. The lightweight is integrated into Prometheus, and it uses PromQL to query the data from Prometheus, so it should be adopted easily. But due to the cardinality constraint of Prometheus, we group the detailed data into buckets which throw away the detailed information. We provide much more detailed information for the standard version because we use ElasticSearch as the back-end to store the original information.

The lightweight version will be open sourced first and the standard version is under ative devlopment and will open sourced in next few months.
The lightweight version will be open-sourced first and the standard version is under active development and will be open-sourced in the next few months.

| Feature | Lightweight | Standard |
| ------------------------------------------------ | ----------- | -------- |
Expand All @@ -57,7 +57,7 @@ The lightweight version will be open sourced first and the standard version is u
| Grafana plugin display | √ | √ |
| Network traffic dump | | √ |
| Virtual network packet tracing | | √ |
| Kuberntes infrastructure monitor and integration | | √ |
| Kubernetes infrastructure monitor and integration | | √ |
| Warning and alert | | √ |
| Multi-cluster management | | √ |

Expand All @@ -71,15 +71,15 @@ The Kindling documentation is available at [kindling website]( http://www.kindli

## Contributing

Contributions are welcome, you can contribute in many ways: report issues,help us reproduce issues, fix bugs, add features, or give us advice on github discussions and so on.If you’re interested in joining us to unveil the e BPF in kubernetes area,you can start by reading the [Contributing Guide](https://github.com/Kindling-project/kindling/blob/main/CONTRIBUTING.md).
Contributions are welcome, you can contribute in many ways: report issues, help us reproduce issues, fix bugs, add features, or give us advice on GitHub discussions and so on. If you are interested in joining us to unveil the eBPF in the Kubernetes area, you can start by reading the [Contributing Guide](https://github.com/Kindling-project/kindling/blob/main/CONTRIBUTING.md).

## Contact

if you have questions or ideas, feel free to reach out to us in the following ways:
If you have questions or ideas, please feel free to reach out to us in the following ways:

- Check out our [discussions](https://github.com/Kindling-project/kindling/discussions)
- Join us on our [Slack team](https://join.slack.com/t/kindling-world/shared_invite/zt-1770uhspf-qxBHT47c1iMGO0w23hSR2A)
- Join us from WeChat Group (chinese)
- Join us from WeChat Group (in Chinese)

![img](https://cdn.nlark.com/yuque/0/2022/png/2307576/1643176150105-21390a1c-15e7-4ee4-9f6d-07b1238342d8.png)

Expand Down
Loading