Skip to content

Commit 811a2f7

Browse files
Y0CossY0Coss
authored
Merge pull request #7995 from ovh/sa-log2cust-guides
OVHcloud Load Balancer - TCP / HTTP / HTTPS Logs forwarding
2 parents 4fbe640 + 98176ba commit 811a2f7

File tree

4 files changed

+432
-0
lines changed

4 files changed

+432
-0
lines changed

‎pages/index.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1883,6 +1883,7 @@
18831883
+ [Managing your Load Balancer service via the Control Panel](network/load_balancer/use-lb)
18841884
+ [Load Balancer API Quick Reference](network/load_balancer/use_api_reference)
18851885
+ [Details of API functions](network/load_balancer/use_api_details)
1886+
+ [OVHcloud Load Balancer TCP / HTTP / HTTPS Logs Forwarding](network/load_balancer/use_api_logs_2_customers)
18861887
+ [Order a free SSL certificate](network/load_balancer/order_freecertificate)
18871888
+ [Load Balancer FAQ](network/load_balancer/create_faq)
18881889
+ [Use cases](network-load-balancer-use-cases)

‎pages/network/load_balancer/use_api_logs_2_customers/guide.en-gb.md

Lines changed: 215 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,215 @@
1+
---
2+
title: OVHcloud Load Balancer TCP / HTTP / HTTPS Logs Forwarding
3+
excerpt: Find out how to forward your logs from an OVHcloud Load Balancer to Logs Data Platform
4+
updated: 2025-06-16
5+
---
6+
 
7+
## Objective
8+
9+
The purpose of this guide is to show you how to enable the forwarding of logs from your OVHcloud Load Balancer to Logs Data Platform (LDP), a platform that helps you store, archive, query and visualize your logs.
10+
If you would like to find out more about Logs Data Platform before reading this guide, please refer to the [Logs Data Platform introduction guide](/pages/manage_and_operate/observability/logs_data_platform/getting_started_introduction_to_LDP).
11+
12+
> [!primary]
13+
> In order to use this feature, you must first make a refresh call via the API to the Load Balancers whose logs you want to collect.
14+
> This is necessary to ensure that the logging format of the OVHcloud Load Balancer is up to date.
15+
> You can use the API call below, where **serviceName** is the internal name of your Load Balancer, which you can find in the Load Balancer management page in the OVHcloud Control Panel or using the [dedicated API](https://api.ovh.com/console/?section=%2FipLoadbalancing&branch=v1#get-/ipLoadbalancing) call.
16+
>
17+
18+
> [!api]
19+
>
20+
> @api {v1} /ipLoadbalancing POST /ipLoadbalancing/{serviceName}/refresh
21+
>
22+
23+
## Glossary
24+
25+
- **Logs Data Platform:** a fully managed and secured log management platform by OVHcloud. For more information, consult the [Logs Data Platform](/links/manage-operate/ldp) service page.
26+
- **Data Stream:** a logical partition of logs which you create in an LDP account and which you will use when ingesting, viewing or querying your logs. Multiple sources can be stored in the same data stream, and it is the unit that can be used to define a log pipeline (retention policy, archiving, live streaming, etc.), access rights and alert policies.
27+
- **Logs forwarding:** a feature integrated into an OVHcloud product to ingest the logs of its services into a *Data Stream* of an LDP account in the same OVHcloud account. This feature must be activated by the customer and per service.
28+
- **Logs forwarding Subscription:** when enabling the logs forwarding for a given OVHcloud service to a given LDP *Data Stream*, a *Subscription* is created and attached to the *Data Stream* for further management by the customer.
29+
30+
## Requirements
31+
32+
- A Logs Data Platform (LDP) account with at least one active *Stream* configured. This guide will walk you through all the necessary steps: [Quick start for Logs Data Platform](/pages/manage_and_operate/observability/logs_data_platform/getting_started_quick_start).
33+
- If you are not familiar with all the LDP *Stream* configuration possibilities, simply create a new one with the default options (indexing & websocket enabled, long-term storage disabled) for the purpose of this guide.
34+
- An up-and-running [OVHcloud Load Balancer](/pages/network/load_balancer/use_presentation).
35+
- Both the LDP account and the OVHcloud Load Balancer account must belong to the same OVHcloud account.
36+
37+
### Concepts & limits
38+
39+
> [!warning]
40+
> To date, the logs of the **UDP** listeners are not forwarded.
41+
>
42+
43+
**What are the logs of an OVHcloud Load Balancer?**
44+
45+
The forwarded logs are generated by [HAproxy](https://en.wikipedia.org/wiki/HAProxy){.external} (the opensource component used for load balancing).
46+
47+
### Log content for TCP based listeners : `TCP`, `HTTP`
48+
49+
| Field name | Description | Type |
50+
|------------|-------------|---------|
51+
| service_name | The name of the Load Balancer that received the request/connection | String |
52+
| date_time | The timestamp at which the request/connection was made | datetime (with millisecond resolution) e.g. 25/Mar/2024:14:07:19.536 |
53+
| zone | The OVHcloud region to which the Load Balancer belongs | String |
54+
| client_ip | IP address of the client that initiated the TCP connection to the Load Balancer | IP |
55+
| client_port_int | TCP port of the client that initiated the TCP connection to the Load Balancer | Integer |
56+
| frontend_name | Name of the frontend of your Load Balancer | String |
57+
| frontend_ip | IP address of the frontend of your Load Balancer | IP |
58+
| frontend_port_int | TCP port of the frontend of your Load Balancer | Integer |
59+
| backend_name | Name of the NAT source used by the Load Balancer to connect to your backend servers | String |
60+
| backend_source_ip | Source IP address used by the Load Balancer to connect to your backend servers | IP |
61+
| backend_source_port_int | Source port used by the Load Balancer to connect to your backend servers | Integer |
62+
| server_ip | IP address of the backend server connected to your Load Balancer | IP |
63+
| server_port_int | TCP port of the backend server connected to your Load Balancer | Integer |
64+
| termination_state | The session termination indicator: 2 letters for TCP, 4 letters for HTTP, all the details on [HAProxy documentation page](https://docs.haproxy.org/2.6/configuration.html#8.5){.external}| String (e.g. "----") |
65+
| bytes_read_int | Size (in bytes) of the response sent by the Load Balancer to the client | Integer |
66+
| bytes_uploaded_int | Size (in bytes) of the request sent by the client to the Load Balancer | Integer |
67+
| time_duration_int | The duration (in milliseconds) of the TCP session at the time the request was made | Integer |
68+
69+
### Additional content for `HTTP` listeners
70+
71+
| Field name | Description | Type |
72+
|------------|-------------|---------|
73+
| captured_request_headers | The headers of the HTTP request e.g. "User-Agent" | String |
74+
| http_request | The resource of the HTTP request e.g. "/index.html" | String |
75+
| http_status_code_int | The returned HTTP status e.g. "200" | Integer |
76+
77+
78+
## Instructions
79+
80+
Note that the forwarding activation is free of charge, but you will be charged for the usage of the Logs Data Platform service as per the standard price plan. For LDP pricing, refer to this [page](/links/manage-operate/ldp).
81+
82+
### Enabling Load Balancer Log Forwarding using the OVHcloud Control Panel
83+
84+
This feature is not yet available in the Control Panel.
85+
86+
### Enabling Audit Log Forwarding using APIs
87+
88+
You will have to define the targeted *Stream* of one of your LDP accounts to which you want your logs forwarded. The enablement of the forwarding will create a subscription for this stream id.
89+
90+
You can retrieve the API specifications in the [OVH API Portal](https://api.ovh.com/console-preview/?section=%2Fdbaas%2Flogs&branch=v1#post-/dbaas/logs/-serviceName-/output/graylog/stream).
91+
92+
#### Step 1 - Retrieve your target Stream (and ID)
93+
94+
List data streams of your Logs Data Platform account (enter your LDP ID in the form ldp-xx-xxxx into the field "serviceName"):
95+
96+
> [!api]
97+
>
98+
> @api {v1} /dbaas/logs GET /dbaas/logs/{serviceName}/output/graylog/stream
99+
>
100+
101+
Get the details of a data stream:
102+
103+
> [!api]
104+
>
105+
> @api {v1} /dbaas/logs GET /dbaas/logs/{serviceName}/output/graylog/stream/{streamId}
106+
>
107+
108+
#### Step 2 - Create your subscription
109+
110+
Use the following API call to create a subscription:
111+
112+
> [!api]
113+
>
114+
> @api {v1} /ipLoadbalancing POST /ipLoadbalancing/{serviceName}/log/subscription
115+
>
116+
117+
You will need to replace:
118+
119+
- **serviceName**: this is the internal name of your Load Balancer, you can find it in the Load Balancer management page in the OVHcloud Control Panel or using the [dedicated API](https://api.ovh.com/console/?section=%2FipLoadbalancing&branch=v1#get-/ipLoadbalancing) call.
120+
121+
The POST request has a payload that requires:
122+
123+
- `kind`: the kind of log you want to forward, either "http" or "tcp". You can find available kinds using the [dedicated API](https://api.ovh.com/console/?section=%2FipLoadbalancing&branch=v1#get-/ipLoadbalancing/-serviceName-/log/kind) call.
124+
- `streamId`: the target data stream of your LDP account where you want your Load Balancer logs to be forwarded to.
125+
126+
```shell
127+
POST /ipLoadbalancing/{serviceName}/log/subscription
128+
{
129+
"kind": "string", // "http" or "tcp".
130+
"streamId": "18d602ec-af40-4000-8e59-41ecc8c23f80" // The streamID of the targeted Stream.
131+
}
132+
```
133+
134+
You will get in response an `operationId`:
135+
136+
```shell
137+
{
138+
"operationId": "f550aa1c-89ab-4b1a-81ae-4fba4959966f",
139+
"serviceName": "ldp-xxxxx"
140+
}
141+
```
142+
143+
You can use the `operationId` to retrieve the `subscriptionId` for further management purposes using the following api call:
144+
145+
> [!api]
146+
>
147+
> @api {v1} /dbaas/logs GET /dbaas/logs/{serviceName}/operation/{operationId}
148+
>
149+
150+
Alternatively, once the operation is finished, the subscriptions can be retrieved using the following API call:
151+
152+
> [!api]
153+
>
154+
> @api {v1} /ipLoadbalancing GET /ipLoadbalancing/{serviceName}/log/subscription
155+
>
156+
157+
Once you have the `subscriptionId`, you can get the details using the following API call:
158+
159+
> [!api]
160+
>
161+
> @api {v1} /ipLoadbalancing GET /ipLoadbalancing/{serviceName}/log/subscription/{subscriptionId}
162+
>
163+
164+
```shell
165+
GET /ipLoadbalancing/{serviceName}/log/subscription/{subscriptionId}
166+
167+
{
168+
"createdAt": "2025-05-28T13:41:19.713Z",
169+
"kind": "string",
170+
"resource": {
171+
"name": "string",
172+
"type": "string"
173+
},
174+
"serviceName": "string",
175+
"streamId": "19717204-2e10-4000-8b63-4f080b5d5101",
176+
"subscriptionId": "19717204-2e10-4000-8c42-d7b11c9ce680",
177+
"updatedAt": "2025-05-28T13:41:19.713Z"
178+
}
179+
```
180+
181+
### How to use OVHcloud Load Balancer logs?
182+
183+
Now that your logs are ingested and stored in your Logs Data Platform data stream, you can query your logs and build dashboards to have a graphical representation of your logs using the web-based UI of Graylog.
184+
185+
- In the OVHcloud Control Panel, retrieve the LDP username (ex: logs-xxxx) and its password in your Logs Data Platform account home page. You can refer to the [Quick start guide for Logs Data Platform](/pages/manage_and_operate/observability/logs_data_platform/getting_started_quick_start).
186+
- Open the Graylog web-ui. You can retrieve the link in your account home page or using your Access point depending on your account region (for example: Gravelines region is https://gra1.logs.ovh.com/).
187+
- Log into Graylog using your Logs Data Platform Username and Password.
188+
- Search through your logs across the data stream of your Logs Data Platform account. You can refer to [Graylog writing search queries](https://go2docs.graylog.org/current/making_sense_of_your_log_data/writing_search_queries.html){.external} documentation for details on search syntax.
189+
190+
Refer to the following documentation: [Logs Data Platform - Visualizing, querying and exploiting your logs](/products/observability-logs-data-platform-visualizing-querying-exploiting) for more details about how to use your logs with Logs Data Platform, including how to:
191+
192+
- setup alerts
193+
- view the logs in real time through a WebSocket
194+
- build visualization with OpenSearch Dashboards
195+
- integrate with OpenSearch API
196+
- connect with Grafana
197+
 
198+
### How to manage your subscriptions?
199+
200+
At any time, you can retrieve the subscriptions attached to your Logs Data Platform data stream and choose to disable the forwarding by cancelling your subscription on your stream, so that your Logs Data Platform stream no longer receives your audit logs.
201+
202+
Note that this does not delete the logs stored before the subscription was cancelled, as the data stored in a log stream is immutable unless you delete the entire stream.
203+
204+
To delete your subscription you can use the following API call:
205+
206+
> [!api]
207+
>
208+
> @api {v1} /ipLoadbalancing DELETE /ipLoadbalancing/{serviceName}/log/subscription/{subscriptionId}
209+
>
210+
211+
## Go further
212+
213+
If you need training or technical assistance to implement our solutions, contact your sales representative or click on [this link](/links/professional-services) to get a quote and ask our Professional Services experts for assisting you on your specific use case of your project.
214+
215+
Join our [community of users](/links/community).

0 commit comments

Comments
 (0)