Skip to content

Commit f4cf361

Browse files
skudasovskudasov
committed
try publish book
1 parent 5af57f1 commit f4cf361

File tree

21 files changed

+1340
-39
lines changed

21 files changed

+1340
-39
lines changed

‎.github/workflows/docs.yml‎

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
name: GH Pages Deploy
2+
3+
on:
4+
push:
5+
# paths:
6+
# - "docs/**"
7+
8+
jobs:
9+
build-deploy:
10+
runs-on: ubuntu-latest
11+
steps:
12+
- name: Checkout
13+
uses: actions/checkout@v2
14+
15+
- name: Setup mdBook
16+
uses: peaceiris/actions-mdbook@v1
17+
with:
18+
mdbook-version: '0.4.40'
19+
20+
- name: Build
21+
working-directory: book
22+
run: |
23+
mdbook build
24+
25+
- name: Deploy to GitHub Pages
26+
uses: peaceiris/actions-gh-pages@v3
27+
with:
28+
github_token: ${{ secrets.GITHUB_TOKEN }}
29+
publish_dir: book

‎README.md‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -20,6 +20,9 @@ The Chainlink Testing Framework (CTF) is a blockchain development framework writ
2020

2121
If you're looking to implement a new chain integration for the testing framework, head over to the [blockchain](./blockchain/) directory for more info.
2222

23+
[![Documentation](https://img.shields.io/badge/Documentation-GitHub_Pages-blue?style=for-the-badge)](https://michaelcurrin.github.io/mdbook-quickstart/)
24+
25+
2326
# Content
2427

2528
1. [Libraries](#libraries)

‎book/book.toml‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
[book]
2+
authors = ["skudasov"]
3+
language = "en"
4+
multilingual = false
5+
src = "src"
6+
title = "Chainlink Testing Framework"

‎book/mdbook‎

10.7 MB
Binary file not shown.

‎book/src/SUMMARY.md‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
# Summary
2+
3+
- [Overview](./overview.md)
4+
- [Libraries](./libraries.md)
5+
- [Seth](./libs/seth.md)
6+
- [WASP](./libs/wasp.md)
7+
- [Framework](./framework.md)
8+
- [Components](./components.md)
9+
- [Secrets](./secrets.md)
10+
- [Developing](./developing.md)
11+
- [Releasing modules](./releasing_modules.md)

‎book/src/components.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
# Components

‎book/src/developing.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
# Developing

‎book/src/framework.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
# Framework

‎book/src/libraries.md‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
# Libraries
2+
3+
CTF monorepository contains a set of libraries:
4+
5+
- [WASP](libs/wasp.md) - Scalable protocol-agnostic load testing library for `Go`
6+
- [Havoc](libs/havoc.md) - Chaos testing library
7+
- [Seth](libs/seth.md) - Ethereum client library with transaction tracing and gas bumping

‎book/src/libs/havoc.md‎

Lines changed: 211 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,211 @@
1+
## Havoc
2+
3+
The `havoc` package is a Go library designed to facilitate chaos testing within Kubernetes environments using Chaos Mesh. It offers a structured way to define, execute, and manage chaos experiments as code, directly integrated into Go applications or testing suites. This package simplifies the creation and control of Chaos Mesh experiments, including network chaos, pod failures, and stress testing on Kubernetes clusters.
4+
5+
### Features
6+
7+
- **Chaos Object Management:** Easily create, update, pause, resume, and delete chaos experiments using Go structures and methods.
8+
- **Lifecycle Hooks:** Utilize chaos listeners to hook into lifecycle events of chaos experiments, such as creation, start, pause, resume, and finish.
9+
- **Support for Various Chaos Experiments:** Create and manage different types of chaos experiments like NetworkChaos, IOChaos, StressChaos, PodChaos, and HTTPChaos.
10+
- **Chaos Experiment Status Monitoring:** Monitor and react to the status of chaos experiments programmatically.
11+
12+
### Installation
13+
14+
To use `havoc` in your project, ensure you have a Go environment setup. Then, install the package using go get:
15+
16+
```
17+
go get -u github.com/smartcontractkit/chainlink-testing-framework/havoc
18+
```
19+
20+
Ensure your Kubernetes cluster is accessible and that you have Chaos Mesh installed and configured.
21+
22+
### Monitoring and Observability in Chaos Experiments
23+
24+
`havoc` enhances chaos experiment observability through structured logging and Grafana annotations, facilitated by implementing the ChaosListener interface. This approach allows for detailed monitoring, debugging, and visual representation of chaos experiments' impact.
25+
26+
#### Structured Logging with ChaosLogger
27+
28+
`ChaosLogger` leverages the zerolog library to provide structured, queryable logging of chaos events. It automatically logs key lifecycle events such as creation, start, pause, and termination of chaos experiments, including detailed contextual information.
29+
30+
Instantiate `ChaosLogger` and register it as a listener to your chaos experiments:
31+
32+
```
33+
logger := havoc.NewChaosLogger()
34+
chaos.AddListener(logger)
35+
```
36+
37+
### Default package logger
38+
39+
`havoc/logger.go` contains default `Logger` instance for the package.
40+
41+
#### Visual Monitoring with Grafana Annotations
42+
43+
`SingleLineGrafanaAnnotator` is a `ChaosListener` that annotates Grafana dashboards with chaos experiment events. This visual representation helps correlate chaos events with their effects on system metrics and logs.
44+
45+
Initialize `SingleLineGrafanaAnnotator` with your Grafana instance details and register it alongside `ChaosLogger`:
46+
47+
```
48+
annotator := havoc.NewSingleLineGrafanaAnnotator(
49+
"http://grafana-instance.com",
50+
"grafana-access-token",
51+
"dashboard-uid",
52+
)
53+
chaos.AddListener(annotator)
54+
```
55+
56+
### Creating a Chaos Experiment
57+
58+
To create a chaos experiment, define the chaos object options, initialize a chaos experiment with NewChaos, and then call Create to start the experiment.
59+
60+
Here is an example of creating and starting a PodChaos experiment:
61+
62+
```
63+
package main
64+
65+
import (
66+
"context"
67+
"github.com/smartcontractkit/chainlink-testing-framework/havoc"
68+
"github.com/chaos-mesh/chaos-mesh/api/v1alpha1"
69+
"sigs.k8s.io/controller-runtime/pkg/client"
70+
"time"
71+
)
72+
73+
func main() {
74+
// Initialize dependencies
75+
client, err := havoc.NewChaosMeshClient()
76+
if err != nil {
77+
panic(err)
78+
}
79+
logger := havoc.NewChaosLogger()
80+
annotator := havoc.NewSingleLineGrafanaAnnotator(
81+
"http://grafana-instance.com",
82+
"grafana-access-token",
83+
"dashboard-uid",
84+
)
85+
86+
// Define chaos experiment
87+
podChaos := &v1alpha1.PodChaos{ /* PodChaos spec */ }
88+
chaos, err := havoc.NewChaos(havoc.ChaosOpts{
89+
Object: podChaos,
90+
Description: "Pod failure example",
91+
DelayCreate: 5 * time.Second,
92+
Client: client,
93+
})
94+
if err != nil {
95+
panic(err)
96+
}
97+
98+
// Register listeners
99+
chaos.AddListener(logger)
100+
chaos.AddListener(annotator)
101+
102+
// Start chaos experiment
103+
chaos.Create(context.Background())
104+
105+
// Manage chaos lifecycle...
106+
}
107+
```
108+
109+
### Test Example
110+
111+
```
112+
func TestChaosDON(t *testing.T) {
113+
testDuration := time.Minute * 60
114+
115+
// Load test config
116+
cfg := &config.MercuryQAEnvChaos{}
117+
118+
// Define chaos experiments and their schedule
119+
120+
k8sClient, err := havoc.NewChaosMeshClient()
121+
require.NoError(t, err)
122+
123+
// Test 3.2: Disable 2 nodes simultaneously
124+
125+
podFailureChaos4, err := k8s_chaos.MercuryPodChaosSchedule(k8s_chaos.MercuryScheduledPodChaosOpts{
126+
Name: "schedule-don-ocr-node-failure-4",
127+
Description: "Disable 2 nodes (clc-ocr-mercury-arb-testnet-qa-nodes-3 and clc-ocr-mercury-arb-testnet-qa-nodes-4)",
128+
DelayCreate: time.Minute * 0,
129+
Duration: time.Minute * 20,
130+
Namespace: cfg.ChaosNodeNamespace,
131+
PodSelector: v1alpha1.PodSelector{
132+
Mode: v1alpha1.AllMode,
133+
Selector: v1alpha1.PodSelectorSpec{
134+
GenericSelectorSpec: v1alpha1.GenericSelectorSpec{
135+
Namespaces: []string{cfg.ChaosNodeNamespace},
136+
ExpressionSelectors: v1alpha1.LabelSelectorRequirements{
137+
{
138+
Key: "app.kubernetes.io/instance",
139+
Operator: "In",
140+
Values: []string{
141+
"clc-ocr-mercury-arb-testnet-qa-nodes-3",
142+
"clc-ocr-mercury-arb-testnet-qa-nodes-4",
143+
},
144+
},
145+
},
146+
},
147+
},
148+
},
149+
Client: k8sClient,
150+
})
151+
require.NoError(t, err)
152+
153+
// Test 3.3: Disable 3 nodes simultaneously
154+
155+
podFailureChaos5, err := k8s_chaos.MercuryPodChaosSchedule(k8s_chaos.MercuryScheduledPodChaosOpts{
156+
Name: "schedule-don-ocr-node-failure-5",
157+
Description: "Disable 3 nodes (clc-ocr-mercury-arb-testnet-qa-nodes-3, clc-ocr-mercury-arb-testnet-qa-nodes-4 and clc-ocr-mercury-arb-testnet-qa-nodes-5)",
158+
DelayCreate: time.Minute * 40,
159+
Duration: time.Minute * 20,
160+
Namespace: cfg.ChaosNodeNamespace,
161+
PodSelector: v1alpha1.PodSelector{
162+
Mode: v1alpha1.AllMode,
163+
Selector: v1alpha1.PodSelectorSpec{
164+
GenericSelectorSpec: v1alpha1.GenericSelectorSpec{
165+
Namespaces: []string{cfg.ChaosNodeNamespace},
166+
ExpressionSelectors: v1alpha1.LabelSelectorRequirements{
167+
{
168+
Key: "app.kubernetes.io/instance",
169+
Operator: "In",
170+
Values: []string{
171+
"clc-ocr-mercury-arb-testnet-qa-nodes-3",
172+
"clc-ocr-mercury-arb-testnet-qa-nodes-4",
173+
"clc-ocr-mercury-arb-testnet-qa-nodes-5",
174+
},
175+
},
176+
},
177+
},
178+
},
179+
},
180+
Client: k8sClient,
181+
})
182+
require.NoError(t, err)
183+
184+
chaosList := []havoc.ChaosEntity{
185+
podFailureChaos4,
186+
podFailureChaos5,
187+
}
188+
189+
for _, chaos := range chaosList {
190+
chaos.AddListener(havoc.NewChaosLogger())
191+
chaos.AddListener(havoc.NewSingleLineGrafanaAnnotator(cfg.GrafanaURL, cfg.GrafanaToken, cfg.GrafanaDashboardUID))
192+
193+
// Fail the test if the chaos object already exists
194+
exists, err := havoc.ChaosObjectExists(chaos.GetObject(), k8sClient)
195+
require.NoError(t, err)
196+
require.False(t, exists, "chaos object already exists: %s. Delete it before starting the test", chaos.GetChaosName())
197+
198+
chaos.Create(context.Background())
199+
}
200+
201+
t.Cleanup(func() {
202+
for _, chaos := range chaosList {
203+
// Delete chaos object if it still exists
204+
chaos.Delete(context.Background())
205+
}
206+
})
207+
208+
// Simulate user activity/load for the duration of the chaos experiments
209+
runUserLoad(t, cfg, testDuration)
210+
}
211+
```

0 commit comments

Comments
 (0)