websocket target support #1278

adnull · 2024-08-11T17:06:11Z

According to #1081 this change adds websocket target support to monitor availability and functionality of websocket servers.

This probe provides features as follows:

Basic HTTP authentification
Bearer token
Arbitrary HTTP headers
TLS configuration
Send/Receive sequences with regexp matching to ensure the server is working correctly ( similar to the TCP probe)

New metrics:

probe_websocket_status_code: resulting http status code on the connection
probe_websocket_connection_upgraded: is the connection successfuly upgraded to a websocket connection
probe_websocket_failed_due_to_regex: 1 when send/receive sequence wasn't matched to server messages

CHANGES:

[FEATURE] Add websocket connection prober

Tests updated
Documentation added
CHANGELOG added in release-notes section of PR Desc.

sanya2022 · 2025-06-06T12:57:48Z

Any updates here?

adnull · 2025-06-06T13:23:20Z

Any updates here?

If only.. althrough the year isn't passed yet :)

bilkoua · 2025-10-13T12:21:21Z

Could you either approve this merge or let us know what needs to be revised?
@electron0zero @SuperQ

electron0zero · 2025-10-30T07:59:15Z

config/config.go

 	FailIfNoneMatchesRegexp []string `yaml:"fail_if_none_matches_regexp,omitempty"`
 }

+type WebsocketProbe struct {


can you add tests for the probe config.

electron0zero · 2025-10-30T08:00:45Z

CONFIGURATION.md

+
+```
+
+### `<tls_config>`


I am bit confused by this change in tls_config, why is this added?

can you address this requested change? this looks like a duplicate of the existing <tls_config> section

example.yml

prober/websocket.go

electron0zero · 2025-10-30T09:51:00Z

config/config.go

+	QueryResponse    []QueryResponse  `yaml:"query_response,omitempty"`
+}
+
+type HTTPClientConfig struct {


any reasons to redefine this instead of using config.HTTPClientConfig from github.com/prometheus/common/config package?

we use it in HTTPProbe so it would be a good idea to use the same struct and keep things common and uniform.

config.HTTPClientConfig is used to construct new http client using prometheus internal functions while I need to create a custom Dialer with a set of http headers to establish a connection. I still don't see any way to create raw headers from it, so it needs a third-party implementation to provide full support of the config options (including password files etc). That's why I made my own config structure.

electron0zero · 2025-10-30T09:52:51Z

config/config.go

+	InsecureSkipVerify bool                   `yaml:"insecure_skip_verify,omitempty"`
+}
+
+type HTTPBasicAuth struct {


same comment as HTTPClientConfig, the BasicAuth in the github.com/prometheus/common/config has File support and is more rich, any reasons to NOT use it?

if we use github.com/prometheus/common/config's HTTPClientConfig, we don't need this type.

electron0zero · 2025-10-30T09:56:33Z

prober/websocket.go

+	registry.MustRegister(httpStatusCode)
+
+	dialer := websocket.Dialer{
+		TLSClientConfig: &tls.Config{


once we use the TLSConfig from github.com/prometheus/common/config, please configure more fields so end users can control those.

TLS MinVersion and TLS ServerName seems to be something I can think we need to expose but it also make sense to expose CA cert and client cert configs so folks can configure tls for websocket probes.

electron0zero · 2025-10-30T09:57:05Z

prober/websocket.go

+
+	if len(module.Websocket.QueryResponse) > 0 {
+		probeFailedDueToRegex := prometheus.NewGauge(prometheus.GaugeOpts{
+			Name: "probe_failed_due_to_regex",


same here, please see metric names in other probers and follow their lead.

electron0zero · 2025-10-30T09:57:55Z

prober/websocket.go

+		registry.MustRegister(probeFailedDueToRegex)
+
+		queryMatched := true
+		for _, qr := range module.Websocket.QueryResponse {


nit: this block is deeply nested and hard to read. can you simplify it and make it easier to read please.

electron0zero · 2025-10-30T09:59:42Z

please rebase with master and resolve conflicts and update the PR desc to follow the new PR template: https://github.com/prometheus/blackbox_exporter/blob/master/.github/PULL_REQUEST_TEMPLATE.md 🙏🏼

prober/websocket.go

bilkoua · 2025-11-10T09:25:37Z

@adnull Could you bring the pull request up to date so it can be merged into master? Do you need any help with that?

adnull · 2025-11-10T11:14:54Z

@bilkoua Hi! Will do shortly.

bilkoua · 2025-12-05T10:13:10Z

@adnull any updates? Do you need any help with that?

Signed-off-by: ad <[email protected]>

Signed-off-by: adnull <[email protected]>

Co-authored-by: Suraj Nath <[email protected]> Signed-off-by: Alex <[email protected]>

adnull · 2025-12-05T19:59:03Z

@bilkoua Just rebased on master, fixed suggested things, except using standart http and tls config structures. I can't use prometheus HTTPConfig as TLSConfig as they are only used in prometheus functions and probes whereas I need to make Dialer myself and I'm only able to pass headers into it, so it needs additional implementation to construct headers from prometheus config structures if we want to use it.

bilkoua · 2025-12-08T18:50:34Z

@adnull Thank you very much. Could you also fix ci/circleci: test and DCO? Without that, it’s unlikely we’ll be able to proceed with the pull request.

Signed-off-by: adnull <[email protected]>

adnull · 2025-12-08T21:29:29Z

@bilkoua Sure, fixed the things

Signed-off-by: adnull <[email protected]>

bilkoua · 2025-12-11T12:52:06Z

@electron0zero Could you take a look at this PR after the changes?

electron0zero · 2026-01-01T10:07:45Z

example.yml

        X-API-Key:
          files:
            - /path/to/api-key.txt
+


Suggested change

trim this line and add the missing newline at the end of file

electron0zero · 2026-01-01T10:17:31Z

CONFIGURATION.md

+```
+
+**Example configurations:**
+


you should link to example.yaml for examples and add all the examples in one place (example.yml), only add the config options exposed by the websocket probe in this page.

electron0zero · 2026-01-01T10:19:48Z

CONFIGURATION.md

+
+```
+
+### `<tls_config>`


can you address this requested change? this looks like a duplicate of the existing <tls_config> section

electron0zero · 2026-01-01T10:20:42Z

CONFIGURATION.md

 ### `<tls_config>`

 ```yml
+[ http_config: <websocket_http_config>]


seems like a stray change? can you remove it?

electron0zero · 2026-01-01T10:22:45Z

CONFIGURATION.md

+[ max_version: <string> ]
+```
+
+#### `<oauth2>`


can this be removed as well, looks like a copy of existing oauth config section?

electron0zero · 2026-01-01T10:25:44Z

config/config.go

+	HTTPHeaders map[string]interface{} `yaml:"headers,omitempty"`
+	BasicAuth   HTTPBasicAuth          `yaml:"basic_auth,omitempty"`
+	BearerToken string                 `yaml:"bearer_token,omitempty"`
+	TLSConfig   *tls.Config            `yaml:"tls_config,omitempty"`


any reasons to not use config.TLSConfig in this case? we use that type across all probes so it's better to stay consistent with TLS config options we expose?

electron0zero · 2026-01-01T10:29:52Z

config/config.go

+type WSHTTPClientConfig struct {
+	HTTPHeaders map[string]interface{} `yaml:"headers,omitempty"`
+	BasicAuth   HTTPBasicAuth          `yaml:"basic_auth,omitempty"`
+	BearerToken string                 `yaml:"bearer_token,omitempty"`


This is a secret so you should be using Secret type from the common/config: https://github.com/prometheus/common/blob/d80d8544703e59a080a204b6f7429ac6561fb24f/config/config.go#L28

if you don't use Secret type in this case, the token will be logged by the logs and will be exposed in the config page.

electron0zero · 2026-01-01T10:37:51Z

config/config.go

+}
+
+type WSHTTPClientConfig struct {
+	HTTPHeaders map[string]interface{} `yaml:"headers,omitempty"`


please use https://github.com/prometheus/common/blob/main/config/headers.go

they have secret type, support for files and validation logic methods that you can reuse those.

see https://github.com/prometheus/common/blob/d80d8544703e59a080a204b6f7429ac6561fb24f/config/headers.go#L116 on how to build headers from all sources.

electron0zero · 2026-01-01T10:40:38Z

config/config.go

+
+type HTTPBasicAuth struct {
+	Username string `yaml:"username"`
+	Password string `yaml:"password"`


password should be Secret type.

electron0zero · 2026-01-01T10:42:48Z

config/config.go

+}
+
+func (c *HTTPBasicAuth) BasicAuthHeader() string {
+	return "Basic " + base64.StdEncoding.EncodeToString([]byte(c.Username+":"+c.Password))


since we are converting the basic auth into a Header, do we need to support a basic auth?

we can just document that they can use Basic Auth with headers and let users set this header by supported methods, including files, etc.

bilkoua · 2026-01-03T09:32:50Z

@electron0zero Thanks
@adnull Could you make these fixes?

adnull force-pushed the websocket-support branch from 19da630 to 9d8f9ec Compare August 11, 2024 17:08

github-actions bot added the stale label Dec 30, 2024

github-actions bot removed the stale label Feb 13, 2025

github-actions bot added the stale label Apr 14, 2025

github-actions bot removed the stale label Jul 1, 2025

github-actions bot added the stale label Sep 1, 2025

electron0zero requested changes Oct 30, 2025

View reviewed changes

electron0zero mentioned this pull request Oct 30, 2025

Request to add support for WebSocket #1081

Open

adnull commented Oct 30, 2025

View reviewed changes

prober/websocket.go Outdated Show resolved Hide resolved

github-actions bot removed the stale label Nov 1, 2025

adnull and others added 4 commits December 5, 2025 20:40

websocket support

0ff78e3

Signed-off-by: ad <[email protected]>

tiny fixes on example

e8866cd

Signed-off-by: adnull <[email protected]>

fix logger errors

7471044

Signed-off-by: adnull <[email protected]>

Fixed metric names

8ab4ad8

Co-authored-by: Suraj Nath <[email protected]> Signed-off-by: Alex <[email protected]>

adnull force-pushed the websocket-support branch from 869a6a3 to 6017309 Compare December 5, 2025 19:52

applied review sugestions

0d8e05f

Signed-off-by: adnull <[email protected]>

adnull force-pushed the websocket-support branch from 6017309 to 0d8e05f Compare December 8, 2025 21:08

mod tidy

99623be

Signed-off-by: adnull <[email protected]>

simplified regexp checking

adfe309

Signed-off-by: adnull <[email protected]>

electron0zero requested changes Jan 1, 2026

View reviewed changes

		```

		Example configurations:

websocket target support #1278

Are you sure you want to change the base?

websocket target support #1278

Uh oh!

Conversation

adnull commented Aug 11, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

sanya2022 commented Jun 6, 2025

Uh oh!

adnull commented Jun 6, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

bilkoua commented Oct 13, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

electron0zero commented Oct 30, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

bilkoua commented Nov 10, 2025

Uh oh!

adnull commented Nov 10, 2025

Uh oh!

bilkoua commented Dec 5, 2025

Uh oh!

adnull commented Dec 5, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

bilkoua commented Dec 8, 2025

Uh oh!

adnull commented Dec 8, 2025

Uh oh!

bilkoua commented Dec 11, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

bilkoua commented Jan 3, 2026

Uh oh!

Reviewers

Assignees

Labels

adnull commented Aug 11, 2024 •

edited

Loading

adnull commented Jun 6, 2025 •

edited

Loading

electron0zero commented Oct 30, 2025 •

edited

Loading

adnull commented Dec 5, 2025 •

edited

Loading