Skip to content

Commit ef26f18

Browse files
TofelTofel
authored
[TT-1717] add docs for lib (#1503)
1 parent ed7d19c commit ef26f18

18 files changed

+915
-10
lines changed

‎book/src/SUMMARY.md‎

Lines changed: 24 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -76,25 +76,41 @@
7676
- [Define NFRs and check alerts](./libs/wasp/how-to/define_nfr_check_alerts.md)
7777
- [Use labels](./libs/wasp/how-to/use_labels.md)
7878
- [Incorporate load tests in your workflow](./libs/wasp/how-to/incorporate_load_tests.md)
79-
- [Reuse dashboard components](./libs/wasp/how-to/reuse_dashboard_components.md)
79+
- [Reuse dashboard components](./libs/wasp/how-to/reuse_dashboard_components.md)
8080
- [Parallelize load](./libs/wasp/how-to/parallelise_load.md)
8181
- [Debug Loki errors](./libs/wasp/how-to/debug_loki_errors.md)
8282
- [Havoc](./libs/havoc.md)
8383
- [K8s Test Runner](k8s-test-runner/k8s-test-runner.md)
8484
- [Sentinel](./libs/sentinel.md)
8585

8686
---
87-
8887
- [Releasing modules](releasing_modules.md)
89-
9088
---
91-
- [Lib (*Deprecated*)](lib.md)
92-
- [Blockchain](lib/blockchain.md)
93-
- [Kubernetes](lib/k8s/KUBERNETES.md)
89+
90+
- [CTFv1 (Discouraged)](lib.md)
91+
- [Blockchain](lib/blockchain.md)
92+
- [Concurrency](lib/concurrency.md)
93+
- [Client](lib/client.md)
94+
- [Anvil]()
95+
- [AWS Secrets Manager](lib/client/aws_secrets_manager.md)
96+
- [Github](lib/client/github.md)
97+
- [Grafana](lib/client/grafana.md)
98+
- [Kafka](lib/client/kafka.md)
99+
- [Loki](lib/client/loki.md)
100+
- [MockServer](lib/client/mockserver.md)
101+
- [Postgres](lib/client/postgres.md)
102+
- [Prometheus](lib/client/prometheus.md)
103+
- [Kubernetes](lib/k8s/KUBERNETES.md)
94104
- [K8s Remote Run](lib/k8s/REMOTE_RUN.md)
95105
- [K8s Tutorial](lib/k8s/TUTORIAL.md)
96106
- [k8s chain.link labels](lib/k8s/labels.md)
97-
- [Config](lib/config/config.md)
98-
- [CRIB Connector](lib/crib.md)
107+
- [Config](lib/config/config.md)
108+
- [CRIB Connector](lib/crib.md)
109+
- [Docker](lib/docker/overview.md)
110+
- [Blockchain nodes](lib/docker/blockchain_nodes.md)
111+
- [Chainlink ecosystem](lib/docker/chainlink_ecosystem.md)
112+
- [Third party apps]()
113+
- [Test helpers](lib/docker/test_helpers.md)
114+
- [Logging](lib/logging.md)
99115
---
100116
- [Build info](build_info.md)

‎book/src/k8s-test-runner/k8s-test-runner.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -27,7 +27,7 @@ Before running tests, you must create a Docker image containing the test binary.
2727
3. Pushes the docker image to the image registry (e.g. Staging ECR)
2828

2929
```sh
30-
go run ./cmd/main.go create-test-image --image-registry-url <staging-ecr-registry-url> --image-tag "<image-tag>" "<path-to-test-folder>"
30+
go run ./cmd/main.go create-test-image --image-registry-url <staging-ecr-registry-url> --image-name "<image-name>" --image-tag "<image-tag>" "<path-to-test-folder>"
3131
```
3232

3333
Where `image-tag` should be a descriptive name for your test, such as "mercury-load-tests".

‎book/src/lib/client.md‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
# Client
2+
3+
We support a variety of clients that ease communication with following applications:
4+
* [Anvil](./client/anvil.md)
5+
* [AWS Secrets Manager](./client/aws_secrets_manager.md)
6+
* [Github](./client/github.md)
7+
* [Kafka](./client/kafka.md)
8+
* [Loki](./client/loki.md)
9+
* [MockServer](./client/mockserver.md)
10+
* [Postgres](./client/postgres.md)
11+
* [Prometheus](./client/prometheus.md)

‎book/src/lib/client/aws_secrets_manager.md‎

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
# AWS Secrets Manager
2+
3+
This simple client makes it even easier to:
4+
* read
5+
* create
6+
* remove secrets from AWS Secrets Manager.
7+
8+
Creating a new instance is straight-forward. You should either use environment variables or shared configuration and credentials.
9+
10+
> [!NOTE]
11+
> Environment variables take precedence over shared credentials.
12+
13+
## Using environment variables
14+
You can pass required configuration as following environment variables:
15+
* `AWS_ACCESS_KEY_ID`
16+
* `AWS_SECRET_ACCESS_KEY`
17+
* `AWS_REGION`
18+
19+
## Using shared credentials
20+
If you have shared credentials stored in `.aws/credentials` file, then the easiest way to configure the client is by setting
21+
`AWS_PROFILE` environment variable with the profile name. If that environment variable is not set, the SDK will try to use default profile.
22+
23+
> [!WARNING]
24+
> Remember, that most probably you will need to manually create a new session for that profile before running your application.
25+
26+
27+
> [!NOTE]
28+
> You can read more about configuring the AWS SDK [here](https://docs.aws.amazon.com/sdk-for-go/v1/developer-guide/configuring-sdk.html).
29+
30+
Once you have an instance of AWS Secrets Manager you gain access to following functions:
31+
* `CreateSecret(key string, val string, override bool) error`
32+
* `GetSecret(key string) (AWSSecret, error)`
33+
* `RemoveSecret(key string, noRecovery bool) error`

‎book/src/lib/client/github.md‎

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
# Github
2+
3+
This small client makes it easy to get `N` latest releases or tags from any Github.com repository. To use it, all you need to have
4+
is a properly scoped access token.
5+
6+
```go
7+
publicRepoClient := NewGithubClient(WITHOUT_TOKEN)
8+
9+
// "smartcontractkit", "chainlink"
10+
latestCLReleases, err := publicRepoClient.ListLatestCLCoreReleases(10)
11+
if err != nil {
12+
panic(err)
13+
}
14+
15+
// "smartcontractkit", "chainlink"
16+
latestCLTags, err := publicRepoClient.ListLatestCLCoreTags(10)
17+
if err != nil {
18+
panic(err)
19+
}
20+
21+
privateRepoClient := NewGithubClient("my-secret-PAT")
22+
myLatestReleases, err := privateRepoClient.ListLatestReleases("my-org", "my-private-repo", 5)
23+
if err != nil {
24+
panic(err)
25+
}
26+
```
27+
28+
There's really not much more to it...

‎book/src/lib/client/grafana.md‎

Lines changed: 80 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,80 @@
1+
# Grafana
2+
3+
> [!NOTE]
4+
> Contrary to other clients, you will find Grafana client in a [separate package & go module](https://github.com/smartcontractkit/chainlink-testing-framework/tree/main/lib/grafana).
5+
6+
Grafana client encapsulate following functionalities:
7+
* Dashboard creation
8+
* Managing dashboard annotations (CRUD)
9+
* Checking alerts
10+
11+
# New instance
12+
In order to create a new instance you will need:
13+
* URL
14+
* API token
15+
16+
For example:
17+
```go
18+
url := "http://grafana.io"
19+
apiToken := "such-a-secret-1&11n"
20+
gc := NewGrafanaClient(url, apiToken)
21+
```
22+
23+
# Dashboard creation
24+
You can create a new dashboard defined in JSON with:
25+
```go
26+
27+
//define your dashboard here
28+
dashboardJson := ``
29+
30+
request := PostDashboardRequest {
31+
Dashboard: dashboardJson,
32+
FolderId: 5 // change to your folder id
33+
}
34+
35+
dr, rawResponse, err := gc.PostDashboard(request)
36+
if err != nil {
37+
panic(err)
38+
}
39+
40+
if rawResponse.StatusCode() != 200 {
41+
panic("response code wasn't 200, but " + rawResponse.StatusCode())
42+
}
43+
44+
fmt.Println("Dashboard slug is is " + *dr.Slug)
45+
```
46+
47+
# Posting annotations
48+
You can post annotations in a following way:
49+
```go
50+
annDetails := PostAnnotation {
51+
DashboardUID: "some-uid",
52+
Time: time.Now(),
53+
TimeEnd: time.Now().Add(1 * time.Second)
54+
Text: "my test annotation"
55+
}
56+
57+
r, rawResponse, err := gc.PostAnnotation(annDetails)
58+
if rawResponse.StatusCode() != 200 {
59+
panic("response code wasn't 200, but " + rawResponse.StatusCode())
60+
}
61+
62+
fmt.Println("Created annotation with id: " + r.Id)
63+
64+
```
65+
66+
# Checking alerts
67+
You can check alerts firing for a dashboard with UID:
68+
```go
69+
alerts, rawResponse, err := gc.AlertRulerClient.GetAlertsForDashboard("some-uid")
70+
if rawResponse.StatusCode() != 200 {
71+
panic("response code wasn't 200, but " + rawResponse.StatusCode())
72+
}
73+
74+
for name, value := range alerts {
75+
fmt.Println("Alert named " + name + "was triggered. Details: " + string(value))
76+
}
77+
```
78+
79+
# Troubleshooting
80+
To enable debug mode for the underlaying HTTP client set `RESTY_DEBUG` environment variable to `true`.

‎book/src/lib/client/kafka.md‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
# Kafka
2+
3+
This is a wrapper over HTTP client that can only return a list of topics from Kafka instance.
4+
5+
```go
6+
client, err := NewKafkaRestClient(&NewKafkaRestClient{URL: "my-kafka-url"})
7+
if err != nil {
8+
panic(err)
9+
}
10+
11+
topis, err := client.GetTopics()
12+
if err != nil {
13+
panic(err)
14+
}
15+
16+
for _, topic := range topics {
17+
fmt.Println("topic: " + topic)
18+
}
19+
```

‎book/src/lib/client/loki.md‎

Lines changed: 63 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,63 @@
1+
# Loki
2+
3+
Loki client simplifies querying of Loki logs with `LogQL`.
4+
5+
The way it's designed now implies that:
6+
* you need to create a new client instance for each query
7+
* query results are returned as `string`
8+
9+
## New instance
10+
To create a new instance you to provide the following at the very least:
11+
* Loki URL
12+
* query to execute
13+
* time range
14+
15+
```go
16+
// scheme is required
17+
lokiUrl := "http://loki-host.io"
18+
// can be empty
19+
tenantId := "promtail"
20+
basicAuth := LokiBasicAuth{
21+
Login: "admin",
22+
Password: "oh-so-secret",
23+
}
24+
queryParams := LokiQueryParams{
25+
Query: "quantile_over_time(0.5, {name='my awesome app'} | json| unwrap duration [10s]) by name",
26+
StartTime: time.Now().Add(1 * time.Hour),
27+
EndTime: time.Now(),
28+
Limit: 1000,
29+
}
30+
lokiClient := client.NewLokiClient(lokiUrl, tenantId, basicAuth, queryParams)
31+
```
32+
33+
If your instance doesn't have basic auth you should use an empty string:
34+
```go
35+
basicAuth := LokiBasicAuth{}
36+
```
37+
38+
## Executing a query
39+
Once you have the client instance created you can execute the query with:
40+
```go
41+
ctx, cancelFn := context.WithTimeout(context.Background, 3 * time.Minute)
42+
defer cancelFn()
43+
results, err := lokiClient.QueryLogs(ctx)
44+
if err != nil {
45+
panic(err)
46+
}
47+
48+
for _, logEntry := range results {
49+
fmt.Println("At " + logEntry.Timestamp + " found following log: " + logEntry.Log)
50+
}
51+
```
52+
53+
## Log entry types
54+
Loki can return various data types in responses to queries. We will try to convert the following ones to `string`:
55+
* `int`
56+
* `float64`
57+
58+
If it's neither of these types nor a `string` the client will return an error. Same will happen if `nil` is returned.
59+
60+
# Troubleshooting
61+
If you find yourself in trouble these two environment variables might help you:
62+
* `RESTY_DEBUG` set to `true` will enable debug mode for the underlaying HTTP client
63+
* `LOKI_CLIENT_LOG_LEVEL` controls log level of Loki client (for supported log levels check [logging package](../logging.md) documentation)

0 commit comments

Comments
 (0)