Skip to content

Commit

Permalink
fix links in go.d.plugin (netdata#17108)
Browse files Browse the repository at this point in the history
  • Loading branch information
ilyam8 authored Mar 5, 2024
1 parent 1116111 commit f517f5a
Show file tree
Hide file tree
Showing 17 changed files with 149 additions and 133 deletions.
176 changes: 88 additions & 88 deletions src/go/collectors/go.d.plugin/README.md

Large diffs are not rendered by default.

62 changes: 39 additions & 23 deletions src/go/collectors/go.d.plugin/docs/how-to-write-a-module.md
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
<!--
title: "How to write a Netdata collector in Go"
description: "This guide will walk you through the technical implementation of writing a new Netdata collector in Golang, with tips on interfaces, structure, configuration files, and more."
custom_edit_url: "https://github.com/netdata/go.d.plugin/edit/master/docs/how-to-write-a-module.md"
custom_edit_url: "https://github.com/netdata/netdata/blob/master/src/go/collectors/go.d.plugin/docs/how-to-write-a-module.md"
sidebar_label: "How to write a Netdata collector in Go"
learn_status: "Published"
learn_topic_type: "Tasks"
Expand All @@ -20,38 +20,43 @@ sidebar_position: 20
locally the **forked** repository (e.g `git clone https://github.com/odyslam/go.d.plugin`).
- Using a terminal, `cd` into the directory (e.g `cd go.d.plugin`)


## Write and test a simple collector

> :exclamation: You can skip most of these steps if you first experiment directy with the existing
> [example module](https://github.com/netdata/go.d.plugin/tree/master/modules/example), which will
> give you an idea of how things work.
> :exclamation: You can skip most of these steps if you first experiment directy with the existing
> [example module](https://github.com/netdata/netdata/tree/master/src/go/collectors/go.d.plugin/modules/example), which
> will
> give you an idea of how things work.
Let's assume you want to write a collector named `example2`.

The steps are:

- Add the source code to [`modules/example2/`](https://github.com/netdata/go.d.plugin/tree/master/modules).
- Add the source code
to [`modules/example2/`](https://github.com/netdata/netdata/tree/master/src/go/collectors/go.d.plugin/modules).
- [module interface](#module-interface).
- [suggested module layout](#module-layout).
- [helper packages](#helper-packages).
- Add the configuration to [`config/go.d/example2.conf`](https://github.com/netdata/go.d.plugin/tree/master/config/go.d).
- Add the module to [`config/go.d.conf`](https://github.com/netdata/netdata/blob/master/src/go/collectors/go.d.plugin/config/go.d.conf).
- Import the module in [`modules/init.go`](https://github.com/netdata/netdata/blob/master/src/go/collectors/go.d.plugin/modules/init.go).
- Update the [`available modules list`](https://github.com/netdata/go.d.plugin#available-modules).
- Add the configuration
to [`config/go.d/example2.conf`](https://github.com/netdata/netdata/tree/master/src/go/collectors/go.d.plugin/config/go.d).
- Add the module
to [`config/go.d.conf`](https://github.com/netdata/netdata/blob/master/src/go/collectors/go.d.plugin/config/go.d.conf).
- Import the module
in [`modules/init.go`](https://github.com/netdata/netdata/blob/master/src/go/collectors/go.d.plugin/modules/init.go).
- Update
the [`available modules list`](https://github.com/netdata/netdata/tree/master/src/go/collectors/go.d.plugin#available-modules).
- To build it, run `make` from the plugin root dir. This will create a new `go.d.plugin` binary that includes your newly
developed collector. It will be placed into the `bin` directory (e.g `go.d.plugin/bin`)
- Run it in the debug mode `bin/godplugin -d -m <MODULE_NAME>`. This will output the `STDOUT` of the collector, the same
output that is sent to the Netdata Agent and is transformed into charts. You can read more about this collector API in
our [documentation](https://github.com/netdata/netdata/blob/master/src/collectors/plugins.d/README.md#external-plugins-api).
- If you want to test the collector with the actual Netdata Agent, you need to replace the `go.d.plugin` binary that
exists in the Netdata Agent installation directory with the one you just compiled. Once
you [restart](https://github.com/netdata/netdata/blob/master/packaging/installer/README.md#maintaining-a-netdata-agent-installation) the Netdata Agent, it will detect and run
you [restart](https://github.com/netdata/netdata/blob/master/packaging/installer/README.md#maintaining-a-netdata-agent-installation)
the Netdata Agent, it will detect and run
it, creating all the charts. It is advised not to remove the default `go.d.plugin` binary, but simply rename it
to `go.d.plugin.old` so that the Agent doesn't run it, but you can easily rename it back once you are done.
- Run `make clean` when you are done with testing.


## Module Interface

Every module should implement the following interface:
Expand Down Expand Up @@ -116,13 +121,16 @@ func (e *Example) Check() bool {

### Charts method

:exclamation: Netdata module produces [`charts`](https://github.com/netdata/netdata/blob/master/src/collectors/plugins.d/README.md#chart), not
:exclamation: Netdata module
produces [`charts`](https://github.com/netdata/netdata/blob/master/src/collectors/plugins.d/README.md#chart), not
raw metrics.

Use [`agent/module`](https://github.com/netdata/netdata/blob/master/src/go/collectors/go.d.plugin/agent/module/charts.go) package to create them,
Use [`agent/module`](https://github.com/netdata/netdata/blob/master/src/go/collectors/go.d.plugin/agent/module/charts.go)
package to create them,
it contains charts and dimensions structs.

- `Charts` returns the [charts](https://github.com/netdata/netdata/blob/master/src/collectors/plugins.d/README.md#chart) (`*module.Charts`).
- `Charts` returns
the [charts](https://github.com/netdata/netdata/blob/master/src/collectors/plugins.d/README.md#chart) (`*module.Charts`).
- Called after `Check` and only if `Check` returned `true`.
- If it returns `nil`, the job will be disabled
- :warning: Make sure not to share returned value between module instances (jobs).
Expand Down Expand Up @@ -196,7 +204,8 @@ Suggested minimal layout:

### File `module_name.go`

> :exclamation: See the example [`example.go`](https://github.com/netdata/netdata/blob/master/src/go/collectors/go.d.plugin/modules/example/example.go).
> :exclamation: See the
> example [`example.go`](https://github.com/netdata/netdata/blob/master/src/go/collectors/go.d.plugin/modules/example/example.go).
Don't overload this file with the implementation details.

Expand All @@ -208,13 +217,15 @@ Usually it contains only:

### File `charts.go`

> :exclamation: See the example: [`charts.go`](https://github.com/netdata/netdata/blob/master/src/go/collectors/go.d.plugin/modules/example/charts.go).
> :exclamation: See the
> example: [`charts.go`](https://github.com/netdata/netdata/blob/master/src/go/collectors/go.d.plugin/modules/example/charts.go).
Put charts, charts templates and charts constructor functions in this file.

### File `init.go`

> :exclamation: See the example: [`init.go`](https://github.com/netdata/netdata/blob/master/src/go/collectors/go.d.plugin/modules/example/init.go).
> :exclamation: See the
> example: [`init.go`](https://github.com/netdata/netdata/blob/master/src/go/collectors/go.d.plugin/modules/example/init.go).
All the module initialization details should go in this file.

Expand All @@ -240,7 +251,8 @@ func (e *Example) initSomeValue() error {

### File `collect.go`

> :exclamation: See the example: [`collect.go`](https://github.com/netdata/netdata/blob/master/src/go/collectors/go.d.plugin/modules/example/collect.go).
> :exclamation: See the
> example: [`collect.go`](https://github.com/netdata/netdata/blob/master/src/go/collectors/go.d.plugin/modules/example/collect.go).
This file is the entry point for the metrics collection.

Expand All @@ -262,11 +274,14 @@ func (e *Example) collect() (map[string]int64, error) {

### File `module_name_test.go`

> :exclamation: See the example: [`example_test.go`](https://github.com/netdata/netdata/blob/master/src/go/collectors/go.d.plugin/modules/example/example_test.go).
> :exclamation: See the
> example: [`example_test.go`](https://github.com/netdata/netdata/blob/master/src/go/collectors/go.d.plugin/modules/example/example_test.go).
> if you have no experience in testing we recommend starting with [testing package documentation](https://golang.org/pkg/testing/).
> if you have no experience in testing we recommend starting
> with [testing package documentation](https://golang.org/pkg/testing/).
> we use `assert` and `require` packages from [github.com/stretchr/testify](https://github.com/stretchr/testify) library,
> we use `assert` and `require` packages from [github.com/stretchr/testify](https://github.com/stretchr/testify)
> library,
> check [their documentation](https://pkg.go.dev/github.com/stretchr/testify).
Testing is mandatory.
Expand All @@ -285,5 +300,6 @@ be [`testdata`](https://golang.org/cmd/go/#hdr-Package_lists_and_patterns).
## Helper packages

There are [some helper packages](https://github.com/netdata/go.d.plugin/tree/master/pkg) for writing a module.
There are [some helper packages](https://github.com/netdata/netdata/tree/master/src/go/collectors/go.d.plugin/pkg) for
writing a module.

4 changes: 2 additions & 2 deletions src/go/collectors/go.d.plugin/modules/coredns/metadata.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -70,7 +70,7 @@ modules:
detailed_description: |
Metrics of servers matching the selector will be collected.
- Logic: (pattern1 OR pattern2) AND !(pattern3 or pattern4)
- Pattern syntax: [matcher](https://github.com/netdata/go.d.plugin/tree/master/pkg/matcher#supported-format).
- Pattern syntax: [matcher](https://github.com/netdata/netdata/tree/master/src/go/collectors/go.d.plugin/pkg/matcher#supported-format).
- Syntax:
```yaml
Expand All @@ -89,7 +89,7 @@ modules:
detailed_description: |
Metrics of zones matching the selector will be collected.
- Logic: (pattern1 OR pattern2) AND !(pattern3 or pattern4)
- Pattern syntax: [matcher](https://github.com/netdata/go.d.plugin/tree/master/pkg/matcher#supported-format).
- Pattern syntax: [matcher](https://github.com/netdata/netdata/tree/master/src/go/collectors/go.d.plugin/pkg/matcher#supported-format).
- Syntax:
```yaml
Expand Down
4 changes: 2 additions & 2 deletions src/go/collectors/go.d.plugin/modules/httpcheck/metadata.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -82,7 +82,7 @@ modules:
default_value: ""
required: true
- name: headers_match.value
description: "The [pattern](https://github.com/netdata/go.d.plugin/tree/master/pkg/matcher#supported-format) to match against the value of the specified header."
description: "The [pattern](https://github.com/netdata/netdata/tree/master/src/go/collectors/go.d.plugin/pkg/matcher#supported-format) to match against the value of the specified header."
default_value: ""
required: false
- name: cookie_file
Expand Down Expand Up @@ -176,7 +176,7 @@ modules:
- 200
- 204
- name: With `header_match`
description: Example configurations with `header_match`. See the value [pattern](https://github.com/netdata/go.d.plugin/tree/master/pkg/matcher#supported-format) syntax.
description: Example configurations with `header_match`. See the value [pattern](https://github.com/netdata/netdata/tree/master/src/go/collectors/go.d.plugin/pkg/matcher#supported-format) syntax.
config: |
jobs:
# The "X-Robots-Tag" header must be present in the HTTP response header,
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -69,7 +69,7 @@ modules:
detailed_description: |
List of IP pools to monitor.
- IP range syntax: see [supported formats](https://github.com/netdata/go.d.plugin/tree/master/pkg/iprange#supported-formats).
- IP range syntax: see [supported formats](https://github.com/netdata/netdata/tree/master/src/go/collectors/go.d.plugin/pkg/iprange#supported-formats).
- Syntax:
```yaml
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -104,7 +104,7 @@ modules:
Metrics of databases matching the selector will be collected.
- Logic: (pattern1 OR pattern2) AND !(pattern3 or pattern4)
- Pattern syntax: [matcher](https://github.com/netdata/go.d.plugin/tree/master/pkg/matcher#supported-format).
- Pattern syntax: [matcher](https://github.com/netdata/netdata/tree/master/src/go/collectors/go.d.plugin/pkg/matcher#supported-format).
- Syntax:
```yaml
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -84,7 +84,7 @@ modules:
Metrics of users matching the selector will be collected.
- Logic: (pattern1 OR pattern2) AND !(pattern3 or pattern4)
- Pattern syntax: [matcher](https://github.com/netdata/go.d.plugin/tree/master/pkg/matcher#supported-format).
- Pattern syntax: [matcher](https://github.com/netdata/netdata/tree/master/src/go/collectors/go.d.plugin/pkg/matcher#supported-format).
- Syntax:
```yaml
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -71,7 +71,7 @@ modules:
details: |
Metrics of users matching the selector will be collected.
- Logic: (pattern1 OR pattern2) AND !(pattern3 or pattern4)
- Pattern syntax: [matcher](https://github.com/netdata/go.d.plugin/tree/master/pkg/matcher#supported-format).
- Pattern syntax: [matcher](https://github.com/netdata/netdata/tree/master/src/go/collectors/go.d.plugin/pkg/matcher#supported-format).
- Syntax:
```yaml
per_user_stats:
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -98,7 +98,7 @@ modules:
default_value: 2
required: false
- name: collect_databases_matching
description: Databases selector. Determines which database metrics will be collected. Syntax is [simple patterns](https://github.com/netdata/go.d.plugin/tree/master/pkg/matcher#simple-patterns-matcher).
description: Databases selector. Determines which database metrics will be collected. Syntax is [simple patterns](https://github.com/netdata/netdata/tree/master/src/go/collectors/go.d.plugin/pkg/matcher#simple-patterns-matcher).
default_value: ""
required: false
- name: max_db_tables
Expand Down
2 changes: 1 addition & 1 deletion src/go/collectors/go.d.plugin/modules/weblog/metadata.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -124,7 +124,7 @@ modules:
default_value: ""
required: true
- name: url_patterns.pattern
description: Used to match against full original request URI. Pattern syntax in [matcher](https://github.com/netdata/go.d.plugin/tree/master/pkg/matcher#supported-format).
description: Used to match against full original request URI. Pattern syntax in [matcher](https://github.com/netdata/netdata/tree/master/src/go/collectors/go.d.plugin/pkg/matcher#supported-format).
default_value: ""
required: true
- name: parser
Expand Down
8 changes: 4 additions & 4 deletions src/go/collectors/go.d.plugin/pkg/README.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
<!--
title: "Helper Packages"
custom_edit_url: "https://github.com/netdata/go.d.plugin/edit/master/pkg/README.md"
custom_edit_url: "https://github.com/netdata/netdata/blob/master/src/go/collectors/go.d.plugin/pkg/README.md"
sidebar_label: "Helper Packages"
learn_status: "Published"
learn_rel_path: "Developers/External plugins/go.d.plugin/Helper Packages"
Expand All @@ -10,13 +10,13 @@ learn_rel_path: "Developers/External plugins/go.d.plugin/Helper Packages"

- if you need IP ranges consider to
use [`iprange`](https://github.com/netdata/netdata/blob/master/src/go/collectors/go.d.plugin/pkg/iprange/README.md).
- if you parse an application log files, then [`log`](https://github.com/netdata/go.d.plugin/tree/master/pkg/logs) is
- if you parse an application log files, then [`log`](https://github.com/netdata/netdata/tree/master/src/go/collectors/go.d.plugin/pkg/logs) is
handy.
- if you need filtering
check [`matcher`](https://github.com/netdata/netdata/blob/master/src/go/collectors/go.d.plugin/pkg/matcher/README.md).
- if you collect metrics from an HTTP endpoint use [`web`](https://github.com/netdata/go.d.plugin/tree/master/pkg/web).
- if you collect metrics from an HTTP endpoint use [`web`](https://github.com/netdata/netdata/tree/master/src/go/collectors/go.d.plugin/pkg/web).
- if you collect metrics from a prometheus endpoint,
then [`prometheus`](https://github.com/netdata/go.d.plugin/tree/master/pkg/prometheus)
then [`prometheus`](https://github.com/netdata/netdata/tree/master/src/go/collectors/go.d.plugin/pkg/prometheus)
and [`web`](https://github.com/netdata/netdata/blob/master/src/go/collectors/go.d.plugin/pkg/web/README.md) is what you need.
- [`tlscfg`](https://github.com/netdata/netdata/blob/master/src/go/collectors/go.d.plugin/pkg/tlscfg/README.md) provides TLS support.
- [`stm`](https://github.com/netdata/netdata/blob/master/src/go/collectors/go.d.plugin/pkg/stm/README.md) helps you to convert any struct to a `map[string]int64`.
2 changes: 1 addition & 1 deletion src/go/collectors/go.d.plugin/pkg/iprange/README.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
<!--
title: "iprange"
custom_edit_url: "https://github.com/netdata/go.d.plugin/edit/master/pkg/iprange/README.md"
custom_edit_url: "https://github.com/netdata/netdata/blob/master/src/go/collectors/go.d.plugin/pkg/iprange/README.md"
sidebar_label: "iprange"
learn_status: "Published"
learn_rel_path: "Developers/External plugins/go.d.plugin/Helper Packages"
Expand Down
2 changes: 1 addition & 1 deletion src/go/collectors/go.d.plugin/pkg/matcher/README.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
<!--
title: "matcher"
custom_edit_url: "https://github.com/netdata/go.d.plugin/edit/master/pkg/matcher/README.md"
custom_edit_url: "https://github.com/netdata/netdata/blob/master/src/go/collectors/go.d.plugin/pkg/matcher/README.md"
sidebar_label: "matcher"
learn_status: "Published"
learn_rel_path: "Developers/External plugins/go.d.plugin/Helper Packages"
Expand Down
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
<!--
title: "Time series selector"
custom_edit_url: "https://github.com/netdata/go.d.plugin/edit/master/pkg/prometheus/selector/README.md"
custom_edit_url: "https://github.com/netdata/netdata/blob/master/src/go/collectors/go.d.plugin/pkg/prometheus/selector/README.md"
sidebar_label: "Time series selector"
learn_status: "Published"
learn_rel_path: "Developers/External plugins/go.d.plugin/Helper Packages"
Expand Down
2 changes: 1 addition & 1 deletion src/go/collectors/go.d.plugin/pkg/stm/README.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
<!--
title: "stm"
custom_edit_url: "https://github.com/netdata/go.d.plugin/edit/master/pkg/stm/README.md"
custom_edit_url: "https://github.com/netdata/netdata/blob/master/src/go/collectors/go.d.plugin/pkg/stm/README.md"
sidebar_label: "stm"
learn_status: "Published"
learn_rel_path: "Developers/External plugins/go.d.plugin/Helper Packages"
Expand Down
4 changes: 2 additions & 2 deletions src/go/collectors/go.d.plugin/pkg/tlscfg/README.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
<!--
title: "tlscfg"
custom_edit_url: "https://github.com/netdata/go.d.plugin/edit/master/pkg/tlscfg/README.md"
custom_edit_url: "https://github.com/netdata/netdata/blob/master/src/go/collectors/go.d.plugin/pkg/tlscfg/README.md"
sidebar_label: "tlscfg"
learn_status: "Published"
learn_rel_path: "Developers/External plugins/go.d.plugin/Helper Packages"
Expand All @@ -27,7 +27,7 @@ Just make `TLSConfig` part of your module configuration.
```go
package example

import "github.com/netdata/go.d.plugin/pkg/tlscfg"
import "github.com/netdata/netdata/go/go.d.plugin/pkg/tlscfg"

type Config struct {
tlscfg.TLSConfig `yaml:",inline"`
Expand Down
4 changes: 2 additions & 2 deletions src/go/collectors/go.d.plugin/pkg/web/README.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
<!--
title: "web"
custom_edit_url: "https://github.com/netdata/go.d.plugin/edit/master/pkg/web/README.md"
custom_edit_url: "https://github.com/netdata/netdata/blob/master/src/go/collectors/go.d.plugin/pkg/web/README.md"
sidebar_label: "web"
learn_status: "Published"
learn_rel_path: "Developers/External plugins/go.d.plugin/Helper Packages"
Expand Down Expand Up @@ -46,7 +46,7 @@ Just make `HTTP` part of your module configuration.
```go
package example

import "github.com/netdata/go.d.plugin/pkg/web"
import "github.com/netdata/netdata/go/go.d.plugin/pkg/web"

type Config struct {
web.HTTP `yaml:",inline"`
Expand Down

0 comments on commit f517f5a

Please sign in to comment.