Skip to content

Commit c36cd25

Browse files
drakirnosslindrakirnosslin
authored
Merge branch 'main' into add-uae-phone-support
2 parents fe6aa7a + fdb2dab commit c36cd25

21 files changed

+175
-146
lines changed

‎site/content/_shared/otel-api-and-endpoint.md

+8-8
Original file line numberDiff line numberDiff line change
@@ -6,15 +6,15 @@ First, make sure to switch on the **Basic HTTP Instrumentation**. This will add
66

77
![Checkly basic OTEL http instrumentation](/docs/images/integrations/otel/otel_basic_instrumentation.png)
88

9-
Then, flip on the "Ingest Traces" section, grab your OTel API key in the **Ingest traces** section of the [Open Telemetry Integration page in the Checkly app](https://app.checklyhq.com/settings/account/open-telemetry) and
9+
Then, toggle on **Send Traces**, grab your OTel API key in the **OTel API keys** section of the [Open Telemetry Integration page in the Checkly app](https://app.checklyhq.com/settings/account/open-telemetry) and
1010
take a note of the endpoint for the region you want to use.
1111

12-
![Checkly OTEL API keys](/docs/images/integrations/otel/otel_ingest_traces.png)
12+
![Checkly OTEL API keys](/docs/images/integrations/otel/otel_send_traces.png)
1313

1414
Now, export your API key in your shell by setting the `OTEL_EXPORTER_OTLP_HEADERS` environment variable.
1515

1616
```bash
17-
export OTEL_EXPORTER_OTLP_HEADERS="authorization=Bearer <your-api-key>"
17+
export OTEL_EXPORTER_OTLP_HEADERS="authorization=<your-api-key>"
1818
```
1919

2020
Next, export the endpoint for the region you want to use and give your service a name.
@@ -29,8 +29,8 @@ During the beta we only have one region available: `eu-west-1`. We will expand t
2929

3030
We are using the standard OpenTelemetry environment variables here to configure the OTLP exporter.
3131

32-
| Variable | Description |
33-
|-------------------------------|-------------------------------------------------------------------------------------------|
34-
| `OTEL_EXPORTER_OTLP_HEADERS` | The `Authorization` HTTP header containing your Checkly OTel API key as a `Bearer` token. |
35-
| `OTEL_EXPORTER_OTLP_ENDPOINT` | The Checkly OTel API endpoint for the region you want to use. |
36-
| `OTEL_SERVICE_NAME` | The name of your service to identify it among the spans in the web UI. |
32+
| Variable | Description |
33+
|-------------------------------|-------------------------------------------------------------------------|
34+
| `OTEL_EXPORTER_OTLP_HEADERS` | The `Authorization` HTTP header containing your Checkly OTel API key. |
35+
| `OTEL_EXPORTER_OTLP_ENDPOINT` | The Checkly OTel API endpoint for the region you want to use. |
36+
| `OTEL_SERVICE_NAME` | The name of your service to identify it among the spans in the web UI. |

‎site/content/docs/open-telemetry/_index.md

+8-14
Original file line numberDiff line numberDiff line change
@@ -12,25 +12,15 @@ beta: true
1212
The OpenTelemetry integration is currently in **beta** and available for free on all plans.
1313
Need help getting started? We offer a **free, 1:1 valet onboarding service** to help you instrument your stack with the
1414
correct OpenTelemetry SDKs and enable tracing inside Checkly.
15-
[Book an onboarding session right here](https://calendly.com/tim-nolet/checkly-open-telemetry)
15+
[Book an onboarding session right here](https://calendly.com/maria-checkly/traces-onboarding)
1616
{{< /info >}}
1717

18-
The Checkly OpenTelemetry (OTel) integration allows you to correlate synthetic monitoring checks with traces from your backend services. This integration is especially useful for two types of users:
19-
20-
- **Resolve issues quicker:** Resolve failing synthetic checks much quicker by correlating failing checks with backend & infrastructure traces. No more flipping between various 3rd party observability (o11y) systems.
21-
- **Increase signal vs. noise:** Cut through the sea of o11y and focus on the data that correlates to critical and known business processes as exercised by synthetic monitoring checks.
22-
- **Save money:** Send traces directly to Checkly, without signing up for another product or hosting an OTel solution yourself.
23-
24-
![Check result with OpenTelemetry trace](/docs/images/integrations/otel/otel_check_result.png)
25-
2618
With OpenTelemetry enabled, you will have access to traces in all the places where it matters to more quickly resolve issues:
2719
- **Check results:** resolve production outages faster by correlating failing checks with backend traces.
2820
- **Test sessions:** understand any failures during test session execution.
2921
- **Check Editors** get a live trace while building, editing and debugging check code.
3022

31-
See this in action in the video below:
32-
33-
<div style="position: relative; padding-bottom: 56.25%; height: 0;"><iframe src="https://www.loom.com/embed/30c143388ba54e9ba6b665dfbfe0d295?sid=8ad8d273-b0bb-48ca-b456-1b137384b9de" frameborder="0" webkitallowfullscreen mozallowfullscreen allowfullscreen style="position: absolute; top: 0; left: 0; width: 100%; height: 100%;"></iframe></div>
23+
![Check result with OpenTelemetry trace](/docs/images/integrations/otel/otel_check_result.png)
3424

3525

3626
<br>
@@ -49,13 +39,17 @@ To get started with the Checkly OpenTelemetry integration, pick a scenario that
4939
class="two-column-card"
5040
headerTag="h3"
5141
title="I have an OpenTelemetry setup"
52-
description="Send traces to your 3rd party OTel backend and ingest them into Checkly too."
42+
description="Export traces to your 3rd party OTel backend and send them into Checkly too."
5343
img="/docs/images/icons/opentelemetry.svg"
54-
link="/docs/open-telemetry/sending-traces/"
44+
link="/docs/open-telemetry/exporting-traces/"
5545
>}}
5646
</div>
5747
5848
<br>
5949

50+
See this in action in the video below:
51+
52+
<div style="position: relative; padding-bottom: 56.25%; height: 0;"><iframe src="https://www.loom.com/embed/30c143388ba54e9ba6b665dfbfe0d295?sid=8ad8d273-b0bb-48ca-b456-1b137384b9de" frameborder="0" webkitallowfullscreen mozallowfullscreen allowfullscreen style="position: absolute; top: 0; left: 0; width: 100%; height: 100%;"></iframe></div>
53+
6054
If you want to learn more about how this all works, check out the [How it works under the hood](/docs/open-telemetry/how-it-works/) section.
6155

‎site/content/docs/open-telemetry/sending-traces/_index.md renamed to ‎site/content/docs/open-telemetry/exporting-traces/_index.md

+7-7
Original file line numberDiff line numberDiff line change
@@ -1,13 +1,13 @@
11
---
2-
title: Sending traces to 3rd party backends
3-
weight: 20
2+
title: Exporting traces to 3rd party backends
3+
weight: 40
44
menu:
55
integrations:
66
parent: "OpenTelemetry (beta)"
77
beta: true
88
---
99

10-
Sending your checks as traces to a 3rd party OpenTelemetry backend is a great way to correlate check runs with other
10+
Exporting your check results as traces to a 3rd party OpenTelemetry backend is a great way to correlate check runs with other
1111
telemetry data. It's also very simple to set up.
1212
<!--more-->
1313

@@ -19,7 +19,7 @@ telemetry data. It's also very simple to set up.
1919
2. Provide the trace endpoint URL and HTTP header with an API key for your preferred 3rd party OpenTelemetry
2020
backend. Done.
2121

22-
![Provide URL and header with authentication](/docs/images/integrations/otel/otel_send_traces.png)
22+
![Provide URL and header with authentication](/docs/images/integrations/otel/otel_export_traces_settings.png)
2323

2424
After you've set this up, Checkly will instrument every HTTP request with a proper `traceparent` and `tracestate` header
2525
and send every check run as a trace to your 3rd party OpenTelemetry backend.
@@ -39,14 +39,14 @@ and send every check run as a trace to your 3rd party OpenTelemetry backend.
3939
headerTag="h3"
4040
title="Grafana Tempo"
4141
img="/docs/images/integrations/otel/backends/grafana-tempo_icon.svg"
42-
link="/docs/open-telemetry/sending-traces/grafana-tempo/"
42+
link="/docs/open-telemetry/exporting-traces/grafana-tempo/"
4343
>}}
4444
{{< doc-card
4545
class="three-column-card"
4646
headerTag="h3"
4747
title="Honeycomb"
4848
img="/docs/images/integrations/otel/backends/honeycomb_icon.svg"
49-
link="/docs/open-telemetry/sending-traces/honeycomb/"
49+
link="/docs/open-telemetry/exporting-traces/honeycomb/"
5050
>}}
5151
</div>
5252
<div class="cards-list">
@@ -55,6 +55,6 @@ and send every check run as a trace to your 3rd party OpenTelemetry backend.
5555
headerTag="h3"
5656
title="New Relic"
5757
img="/docs/images/integrations/otel/backends/newrelic_icon.svg"
58-
link="/docs/open-telemetry/sending-traces/newrelic/"
58+
link="/docs/open-telemetry/exporting-traces/newrelic/"
5959
>}}
6060
</div>

‎site/content/docs/open-telemetry/sending-traces/grafana-tempo.md renamed to ‎site/content/docs/open-telemetry/exporting-traces/grafana-tempo.md

+4-4
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,14 @@
11
---
22
title: Grafana Tempo
33
head:
4-
title: "Sending traces to Grafana Tempo from Checkly"
4+
title: "Exporting traces to Grafana Tempo from Checkly"
55
metatags:
6-
title: "Sending traces to Grafana Tempo from Checkly"
7-
description: "Send traces from Checkly to Grafana Tempo for better observability."
6+
title: "Exporting traces to Grafana Tempo from Checkly"
7+
description: "Export traces from Checkly to Grafana Tempo for better observability."
88
weight: 22
99
menu:
1010
integrations:
11-
parent: "Sending traces to 3rd party backends"
11+
parent: "Exporting traces to 3rd party backends"
1212
beta: true
1313
---
1414

‎site/content/docs/open-telemetry/sending-traces/honeycomb.md renamed to ‎site/content/docs/open-telemetry/exporting-traces/honeycomb.md

+4-4
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,14 @@
11
---
22
title: Honeycomb
33
head:
4-
title: "Sending traces to Honeycomb from Checkly"
4+
title: "Exporting traces to Honeycomb from Checkly"
55
metatags:
6-
title: "Sending traces to Honeycomb from Checkly"
7-
description: "Send traces from Checkly to Honeycomb for better observability."
6+
title: "Exporting traces to Honeycomb from Checkly"
7+
description: "Export traces from Checkly to Honeycomb for better observability."
88
weight: 23
99
menu:
1010
integrations:
11-
parent: "Sending traces to 3rd party backends"
11+
parent: "Exporting traces to 3rd party backends"
1212
beta: true
1313
---
1414

‎site/content/docs/open-telemetry/sending-traces/newrelic.md renamed to ‎site/content/docs/open-telemetry/exporting-traces/newrelic.md

+4-4
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,14 @@
11
---
22
title: New Relic
33
head:
4-
title: "Sending traces to New Relic from Checkly"
4+
title: "Exporting traces to New Relic from Checkly"
55
metatags:
6-
title: "Sending traces to New Relic from Checkly"
7-
description: "Send traces from Checkly to New Relic for better observability."
6+
title: "Exporting traces to New Relic from Checkly"
7+
description: "Export traces from Checkly to New Relic for better observability."
88
weight: 21
99
menu:
1010
integrations:
11-
parent: "Sending traces to 3rd party backends"
11+
parent: "Exporting traces to 3rd party backends"
1212
beta: true
1313
---
1414

‎site/content/docs/open-telemetry/http-vs-grpc-protocols.md

+26
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
---
2+
title: HTTP vs. gRPC OpenTelemetry protocols
3+
head:
4+
title: "Choosing between HTTP and gRPC OpenTelemetry protocols"
5+
metatags:
6+
title: "Choosing between HTTP and gRPC OpenTelemetry protocols"
7+
description: "Learn about the trade-offs between using HTTP and gRPC for sending data to an OpenTelemetry backend."
8+
weight: 60
9+
menu:
10+
integrations:
11+
parent: "OpenTelemetry (beta)"
12+
beta: true
13+
---
14+
Checkly's OTel ingestion endpoint supports both the HTTP and gRPC protocols. The gRPC protocol is the "native"
15+
protocol for OTel, but in 2020 an alternative HTTP protocol was introduced due to some of the downsides gRPC has:
16+
17+
- gRPC tends to come with bigger dependencies in your code base.
18+
- gRPC uses HTTP/2 as its transport layer, which might not be 100% supported in your network infra. Think firewalls, proxies and load balancers.
19+
20+
However, for larger payload and higher throughput scenarios, gRPC is the way to go. It's more efficient and has a smaller
21+
connection overhead.
22+
23+
Different SDKs and languages have different levels of support for gRPC and HTTP. For example, the HTTP protocol is
24+
the default for Node.js, but gRPC is the default for Go. In all cases, we recommend using the default protocol for your
25+
language and SDK.
26+

‎site/content/docs/open-telemetry/instrumenting-code/_index.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@ title: Instrumenting your code with OpenTelemetry
33
metatags:
44
title: "Instrumenting your code with OpenTelemetry"
55
description: "Instrument your application code with OpenTelemetry and send traces to Checkly."
6-
weight: 60
6+
weight: 30
77
menu:
88
integrations:
99
parent: "OpenTelemetry (beta)"

‎site/content/docs/open-telemetry/instrumenting-code/go.md

+1-8
Original file line numberDiff line numberDiff line change
@@ -183,15 +183,8 @@ func otelChecklyFilter(req *http.Request) bool {
183183

184184
{{< markdownpartial "/_shared/otel-api-and-endpoint.md" >}}
185185

186-
187-
Export your API key and endpoint as environment variables in your shell.
188-
189-
```bash
190-
export CHECKLY_OTEL_API_ENDPOINT="otel.eu-west-1.checklyhq.com # EU instance
191-
export CHECKLY_OTEL_API_KEY="<your Checkly OTel API key>"
192-
```
193186
Then run you app as usual:
194187

195188
```bash
196-
go run main.go
189+
go run .
197190
```

‎site/content/docs/open-telemetry/instrumenting-code/nextjs.md

+47-40
Original file line numberDiff line numberDiff line change
@@ -22,65 +22,72 @@ so we can filter out the Checkly traces.
2222

2323
```bash
2424
npm install --save \
25-
@vercel/otel \
26-
@opentelemetry/api \
27-
@opentelemetry/sdk-trace-base \
28-
@opentelemetry/exporter-trace-otlp-http
25+
@vercel/otel \
26+
@opentelemetry/api \
27+
@opentelemetry/sdk-trace-base \
28+
@opentelemetry/exporter-trace-otlp-http
2929
```
3030

31+
{{< warning >}}
32+
Make sure to install v1.9.1 or later of the `@vercel/otel` package as it contains a critical bug fix for Vercel's Edge runtime.
33+
{{< /warning >}}
34+
35+
3136
## Step 2: Initialize the instrumentation
3237

3338
Set the `instrumentationHook` flag to `true` in your Next.js configuration file. This will enable the OpenTelemetry instrumentation.
3439

3540
```js
3641
/** @type {import('next').NextConfig} */
37-
const nextConfig = {
38-
experimental: {
39-
instrumentationHook: true
40-
}
42+
const nextConfig = {
43+
experimental: {
44+
instrumentationHook: true
4145
}
46+
}
4247

4348
module.exports = nextConfig
4449
```
4550

46-
Create a file called `instrumentation.js` at the root of your project and add the following code:
51+
Create a file called `instrumentation.ts` at the root of your project and add the following code:
4752

4853
```ts
49-
// instrumentation.js
50-
54+
// instrumentation.ts
5155
import { registerOTel } from '@vercel/otel'
52-
import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-http'
53-
import { ConsoleSpanExporter, BatchSpanProcessor, SamplingDecision } from '@opentelemetry/sdk-trace-base'
54-
import { trace } from '@opentelemetry/api'
55-
56-
const checklyExporter = new OTLPTraceExporter({
57-
timeoutMillis: 2000,
58-
})
59-
60-
// export spans to console (useful for debugging)
61-
const consoleProcessor = new BatchSpanProcessor(new ConsoleSpanExporter())
62-
const spanProcessors = new BatchSpanProcessor(checklyExporter)
56+
import { SamplingDecision } from '@opentelemetry/sdk-trace-base'
57+
import { trace, Context } from '@opentelemetry/api'
6358

6459
export function register() {
65-
registerOTel({
66-
serviceName: 'acme-next-app',
67-
traceExporter: checklyExporter,
68-
spanProcessors: [consoleProcessor, spanProcessors],
69-
sampler: {
70-
shouldSample: (context, traceId, spanName, spanKind, attributes, links) => {
71-
const isChecklySpan = trace.getSpan(context)?.spanContext()?.traceState?.get('checkly')
72-
if (isChecklySpan) {
73-
return { decision: SamplingDecision.RECORD_AND_SAMPLED }
74-
} else {
75-
return { decision: SamplingDecision.NOT_RECORD }
76-
}
77-
},
78-
},
79-
})
80-
}
60+
registerOTel({
61+
serviceName: 'acme-next-app',
62+
traceExporter: 'auto',
63+
spanProcessors: ['auto'],
64+
traceSampler: {
65+
shouldSample: (context: Context) => {
66+
const isChecklySpan = trace.getSpan(context)?.spanContext()?.traceState?.get('checkly')
67+
if (isChecklySpan) {
68+
console.log('Sampling decision for Checkly span:', SamplingDecision.RECORD_AND_SAMPLED)
69+
return {
70+
decision: SamplingDecision.RECORD_AND_SAMPLED
71+
}
72+
} else {
73+
console.log('Sampling decision for non-Checkly span:', SamplingDecision.NOT_RECORD)
74+
return {
75+
decision: SamplingDecision.NOT_RECORD
76+
}
77+
}
78+
},
79+
},
80+
})
8181
```
8282
83-
Notice the `sampler` configuration. This is a custom, **head-based sampler** that will only sample spans that are generated by Checkly by
83+
Notice that we are using the default exporter and span processor from the `@vercel/otel` package, which is configured by using the `auto` value.
84+
This package is compatible with Vercel's Edge runtime, in contrast to the `@opentelemetry/exporter-trace-otlp-http` package, which is not.
85+
86+
If you are not using Vercel or don't use Vercel's Edge runtime, you can also use the `@opentelemetry/exporter-trace-otlp-http`
87+
and just follow [the regular Node.js instrumentation guide](/docs/open-telemetry/instrumenting-code/nodejs/#step-2-initialize-the-instrumentation).
88+
This is however not required, the above configuration should work just fine on Node.js and Edge runtimes.
89+
90+
Also notice the `sampler` configuration. This is a custom, **head-based sampler** that will only sample spans that are generated by Checkly by
8491
inspecting the trace state. This way you only pay for the egress traffic generated by Checkly and not for any other traffic.
8592
8693
## Step 3: Start your app with the instrumentation
@@ -90,7 +97,7 @@ inspecting the trace state. This way you only pay for the egress traffic generat
9097
If you are using Vercel for hosting your Next.js app, add the above environment variables to your Vercel project settings,
9198
e.g. 👇
9299
93-
![Vercel project OTEL variables](/docs/images/integrations/otel/otel-languages/nextjs_vercel_env_vars.png)
100+
![Vercel project OTEL variables](/docs/images/integrations/otel/otel-languages/otel_vercel_env_vars.png)
94101
95102
96103
## Further reading

‎site/content/docs/open-telemetry/instrumenting-code/nodejs.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -45,7 +45,7 @@ const exporter = new OTLPTraceExporter({
4545

4646
const sdk = new NodeSDK({
4747
instrumentations: [getNodeAutoInstrumentations()],
48-
spanProcessors: new BatchSpanProcessor(exporter),
48+
spanProcessors: [new BatchSpanProcessor(exporter)],
4949
sampler: {
5050
shouldSample: (context, traceId, spanName, spanKind, attributes, links) => {
5151
const isChecklySpan = trace.getSpan(context)?.spanContext()?.traceState?.get('checkly')

0 commit comments

Comments
 (0)