Provide better guidance on regions and domains (#272)

Author: tothmano

apps/hex.mdx

@@ -38,8 +38,10 @@ curl -X 'POST' 'https://AXIOM_DOMAIN/v1/datasets/DATASET_NAME/ingest' \
 ]'
 ```
 
+<Info>
 <ReplaceDatasetToken />
 <ReplaceDomain />
+</Info>
 
 Verify that your data has been ingested correctly by running an APL query in the Axiom UI.
 
@@ -129,8 +131,10 @@ except Exception as e:
     print(f"\nError: {str(e)}")
 ```
 
+<Info>
 <ReplaceDomain />
 <ReplaceDataset />
+</Info>
 
 ## Create map visualisation
 

guides/javascript.mdx

@@ -81,7 +81,9 @@ axiom.ingest('DATASET_NAME', [{ foo: 'bar' }]);
 await axiom.flush();
 ```
 
+<Info>
 <ReplaceDataset />
+</Info>
 
 The client automatically batches events in the background. In most cases, call `flush()` only before your application exits.
 
@@ -94,7 +96,9 @@ const res = await axiom.query(`['DATASET_NAME'] | where foo == 'bar' | limit 100
 console.log(res);
 ```
 
+<Info>
 <ReplaceDataset />
+</Info>
 
 For more examples, see the [examples in GitHub](https://github.com/axiomhq/axiom-js/tree/main/examples).
 

guides/opentelemetry-cloudflare-workers.mdx

@@ -7,7 +7,9 @@ tags: ['guides', 'cloudflare worker', 'otel', 'opentelemetry']
 logoId: 'cloudflareWorkers'
 ---
 
+import ReplaceDomain from "/snippets/replace-domain.mdx"
 import Prerequisites from "/snippets/standard-prerequisites.mdx"
+import ReplaceDatasetToken from "/snippets/replace-dataset-token.mdx"
 
 This guide demonstrates how to configure OpenTelemetry in Cloudflare Workers to send telemetry data to Axiom using the [OTel CF Worker package](https://github.com/evanderkoogh/otel-cf-workers).
 
@@ -57,7 +59,7 @@ const handler = {
 const config: ResolveConfigFn = (env: Env, _trigger) => {
   return {
     exporter: {
-      url: 'https://api.axiom.co/v1/traces',
+      url: 'https://AXIOM_DOMAIN/v1/traces',
       headers: {
         'Authorization': `Bearer ${env.AXIOM_API_TOKEN}`,
         'X-Axiom-Dataset': `${env.AXIOM_DATASET}`
@@ -70,6 +72,10 @@ const config: ResolveConfigFn = (env: Env, _trigger) => {
 export default instrument(handler, config);
 ```
 
+<Info>
+<ReplaceDomain />
+</Info>
+
 ## Wrangler Configuration (`wrangler.toml`)
 
 Configure **`wrangler.toml`** with your Cloudflare account details and set environment variables for the Axiom API token and dataset.
@@ -85,10 +91,14 @@ main = "index.ts"
 
 # Define environment variables here
 [vars]
-AXIOM_API_TOKEN = "API_TOKEN" # Replace API_TOKEN with your actual Axiom API token
-AXIOM_DATASET = "DATASET_NAME" # Replace DATASET_NAME with your actual Axiom dataset name
+AXIOM_API_TOKEN = "API_TOKEN"
+AXIOM_DATASET = "DATASET_NAME"
 ```
 
+<Info>
+<ReplaceDatasetToken />
+</Info>
+
 ## Install Dependencies
 
 Navigate to the root directory of your project and add `@microlabs/otel-cf-workers` and other OTel packages to the `package.json` file.
@@ -249,26 +259,30 @@ Automatic instrumentation uses the **`@microlabs/otel-cf-workers`** package to a
 
 Wrap your Cloudflare Workers script with the `instrument` function from the **`@microlabs/otel-cf-workers`** package. This automatically instruments incoming requests and outbound fetch calls.
 
-```js
-import { instrument } from '@microlabs/otel-cf-workers';
+    ```js
+    import { instrument } from '@microlabs/otel-cf-workers';
 
-export default instrument(yourHandler, yourConfig);
-```
+    export default instrument(yourHandler, yourConfig);
+    ```
 
 2. Configuration: Provide configuration details, including how to export telemetry data and service metadata to Axiom as part of the `instrument` function call.
 
-```js
-const config = (env) => ({
-  exporter: {
-    url: 'https://api.axiom.co/v1/traces',
-    headers: {
-      'Authorization': `Bearer ${env.AXIOM_API_TOKEN}`,
-      'X-Axiom-Dataset': `${env.AXIOM_DATASET}`
-    },
-  },
-  service: { name: 'axiom-cloudflare-workers' },
-});
-```
+    ```js
+    const config = (env) => ({
+      exporter: {
+        url: 'https://AXIOM_DOMAIN/v1/traces',
+        headers: {
+          'Authorization': `Bearer ${env.AXIOM_API_TOKEN}`,
+          'X-Axiom-Dataset': `${env.AXIOM_DATASET}`
+        },
+      },
+      service: { name: 'axiom-cloudflare-workers' },
+    });
+    ```
+
+    <Info>
+    <ReplaceDomain />
+    </Info>
 
 After instrumenting your Worker script, the `@microlabs/otel-cf-workers` package takes care of tracing automatically.
 

guides/opentelemetry-django.mdx

@@ -8,6 +8,8 @@ logoId: 'openTelemetry'
 ---
 
 import Prerequisites from "/snippets/standard-prerequisites.mdx"
+import ReplaceDatasetToken from "/snippets/replace-dataset-token.mdx"
+import ReplaceDomain from "/snippets/replace-domain.mdx"
 
 <Prerequisites />
 {/* list separator */}
@@ -115,7 +117,7 @@ provider = TracerProvider(resource=resource)
 
 # Configure the OTLP/HTTP Span Exporter with necessary headers and endpoint
 otlp_exporter = OTLPSpanExporter(
-    endpoint="https://api.axiom.co/v1/traces",
+    endpoint="https://AXIOM_DOMAIN/v1/traces",
     headers={
         "Authorization": "Bearer API_TOKEN",  # Replace with your actual API token
         "X-Axiom-Dataset": "DATASET_NAME"    # Replace with your dataset name
@@ -133,6 +135,11 @@ trace.set_tracer_provider(provider)
 tracer = trace.get_tracer("your-service-name")
 ```
 
+<Info>
+<ReplaceDomain />
+<ReplaceDatasetToken />
+</Info>
+
 ### Use the tracer in your views
 
 In this step, modify the Django views to use the tracer defined in `exporter.py`. By wrapping the view logic within `tracer.start_as_current_span`, you create spans that capture the execution of these views. This provides detailed insights into the performance of individual request handlers, helping to identify slow operations or errors.
@@ -203,33 +210,38 @@ Manual instrumentation in Python with OpenTelemetry involves adding code to crea
 
 1. Install necessary OpenTelemetry packages to enable manual tracing capabilities in your Django app.
 
-```py
-pip install django opentelemetry-api opentelemetry-sdk opentelemetry-exporter-otlp-proto-http opentelemetry-instrumentation-django
-```
+    ```py
+    pip install django opentelemetry-api opentelemetry-sdk opentelemetry-exporter-otlp-proto-http opentelemetry-instrumentation-django
+    ```
 
 2. Set up OpenTelemetry in your Django project to manually trace app activities.
 
-```py
-# otel_config.py
-from opentelemetry import trace
-from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
-from opentelemetry.sdk.resources import Resource
-from opentelemetry.sdk.trace import TracerProvider
-from opentelemetry.sdk.trace.export import BatchSpanProcessor
-
-def configure_opentelemetry():
-    resource = Resource(attributes={"service.name": "your-django-app"})
-    trace.set_tracer_provider(TracerProvider(resource=resource))
-    otlp_exporter = OTLPSpanExporter(
-        endpoint="https://api.axiom.co/v1/traces",
-        headers={"Authorization": "Bearer API_TOKEN", "X-Axiom-Dataset": "DATASET_NAME"}
-    )
-    span_processor = BatchSpanProcessor(otlp_exporter)
-    trace.get_tracer_provider().add_span_processor(span_processor)
-    return trace.get_tracer(__name__)
-
-tracer = configure_opentelemetry()
-```
+    ```py
+    # otel_config.py
+    from opentelemetry import trace
+    from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
+    from opentelemetry.sdk.resources import Resource
+    from opentelemetry.sdk.trace import TracerProvider
+    from opentelemetry.sdk.trace.export import BatchSpanProcessor
+
+    def configure_opentelemetry():
+        resource = Resource(attributes={"service.name": "your-django-app"})
+        trace.set_tracer_provider(TracerProvider(resource=resource))
+        otlp_exporter = OTLPSpanExporter(
+            endpoint="https://AXIOM_DOMAIN/v1/traces",
+            headers={"Authorization": "Bearer API_TOKEN", "X-Axiom-Dataset": "DATASET_NAME"}
+        )
+        span_processor = BatchSpanProcessor(otlp_exporter)
+        trace.get_tracer_provider().add_span_processor(span_processor)
+        return trace.get_tracer(__name__)
+
+    tracer = configure_opentelemetry()
+    ```
+
+    <Info>
+    <ReplaceDomain />
+    <ReplaceDatasetToken />
+    </Info>
 
 3. Configure OpenTelemetry to your Django settings to capture telemetry data upon app startup.
 
@@ -288,32 +300,37 @@ Automatic instrumentation in Django with OpenTelemetry simplifies the process of
 
 1. Install required packages that support automatic instrumentation.
 
-```bash
-pip install django opentelemetry-api opentelemetry-sdk opentelemetry-exporter-otlp-proto-http opentelemetry-instrumentation-django
-```
+    ```bash
+    pip install django opentelemetry-api opentelemetry-sdk opentelemetry-exporter-otlp-proto-http opentelemetry-instrumentation-django
+    ```
 
 2. Automatically configure OpenTelemetry to trace Django app operations without manual span management.
 
-```py
-# otel_config.py
-from opentelemetry import trace
-from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
-from opentelemetry.instrumentation.django import DjangoInstrumentor
-from opentelemetry.sdk.resources import Resource
-from opentelemetry.sdk.trace import TracerProvider
-from opentelemetry.sdk.trace.export import BatchSpanProcessor
-
-def configure_opentelemetry():
-    resource = Resource(attributes={"service.name": "your-django-app"})
-    trace.set_tracer_provider(TracerProvider(resource=resource))
-    otlp_exporter = OTLPSpanExporter(
-        endpoint="https://api.axiom.co/v1/traces",
-        headers={"Authorization": "Bearer API_TOKEN", "X-Axiom-Dataset": "DATASET_NAME"}
-    )
-    span_processor = BatchSpanProcessor(otlp_exporter)
-    trace.get_tracer_provider().add_span_processor(span_processor)
-    DjangoInstrumentor().instrument()
-```
+    ```py
+    # otel_config.py
+    from opentelemetry import trace
+    from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
+    from opentelemetry.instrumentation.django import DjangoInstrumentor
+    from opentelemetry.sdk.resources import Resource
+    from opentelemetry.sdk.trace import TracerProvider
+    from opentelemetry.sdk.trace.export import BatchSpanProcessor
+
+    def configure_opentelemetry():
+        resource = Resource(attributes={"service.name": "your-django-app"})
+        trace.set_tracer_provider(TracerProvider(resource=resource))
+        otlp_exporter = OTLPSpanExporter(
+            endpoint="https://AXIOM_DOMAIN/v1/traces",
+            headers={"Authorization": "Bearer API_TOKEN", "X-Axiom-Dataset": "DATASET_NAME"}
+        )
+        span_processor = BatchSpanProcessor(otlp_exporter)
+        trace.get_tracer_provider().add_span_processor(span_processor)
+        DjangoInstrumentor().instrument()
+    ```
+
+    <Info>
+    <ReplaceDomain />
+    <ReplaceDatasetToken />
+    </Info>
 
 3. Initialize OpenTelemetry in Django to capture telemetry data from all HTTP requests automatically.
 

guides/opentelemetry-dotnet.mdx

@@ -7,6 +7,8 @@ tags: ['guides', '.NET', 'dotnet', 'OpenTelemetry', 'otel']
 logoId: 'openTelemetry'
 ---
 
+import ReplaceDatasetToken from "/snippets/replace-dataset-token.mdx"
+import ReplaceDomain from "/snippets/replace-domain.mdx"
 import Prerequisites from "/snippets/standard-prerequisites.mdx"
 
 OpenTelemetry provides a [unified approach to collecting telemetry data](https://opentelemetry.io/docs/languages/net/) from your .NET applications. This guide explains how to configure OpenTelemetry in a .NET application to send telemetry data to Axiom using the OpenTelemetry SDK.
@@ -162,9 +164,9 @@ public static class TracingConfiguration
             .AddHttpClientInstrumentation() // Add automatic instrumentation for HttpClient requests
             .AddOtlpExporter(options => // Configure the OTLP exporter
             {
-                options.Endpoint = new Uri("https://api.axiom.co/v1/traces"); // Set the endpoint for the exporter
+                options.Endpoint = new Uri("https://AXIOM_DOMAIN/v1/traces"); // Set the endpoint for the exporter
                 options.Protocol = OpenTelemetry.Exporter.OtlpExportProtocol.HttpProtobuf; // Set the protocol
-                options.Headers = "Authorization=Bearer API_TOKEN, X-Axiom-Dataset=DATASET"; // Update API token and dataset
+                options.Headers = "Authorization=Bearer API_TOKEN, X-Axiom-Dataset=DATASET_NAME"; // Update API token and dataset
             })
             .Build(); // Build the tracer provider
     }
@@ -178,11 +180,11 @@ public static class TracingConfiguration
 }
 ```
 
-In the `tracing.cs` file, make the following changes:
-
-- Replace the value of the `serviceName` variable with the name of the service you want to trace. This is used for identifying and categorizing trace data, particularly in systems with multiple services.
-- Replace `API_TOKEN` with your Axiom API key.
-- Replace `DATASET_NAME` with the name of the Axiom dataset where you want to send data.
+<Info>
+Replace the value of the `serviceName` variable with the name of the service you want to trace. This is used for identifying and categorizing trace data, particularly in systems with multiple services.
+<ReplaceDatasetToken />
+<ReplaceDomain />
+</Info>
 
 ## Run the instrumented application
 
@@ -247,18 +249,22 @@ Automatic instrumentation uses the OpenTelemetry SDK and additional libraries to
 
 1. Configure OpenTelemetry SDK. Use the OpenTelemetry SDK to configure automatic instrumentation in your application. This typically involves setting up a `TracerProvider` in your `program.cs` or startup configuration, which automatically captures telemetry data from supported libraries.
 
-```csharp
-Sdk.CreateTracerProviderBuilder()
-    .AddAspNetCoreInstrumentation()
-    .AddHttpClientInstrumentation()
-    .AddOtlpExporter(options =>
-    {
-        options.Endpoint = new Uri("https://api.axiom.co/v1/traces");
-        // Replace API_TOKEN and DATASET_NAME with your actual API token and dataset name
-        options.Headers = $"Authorization=Bearer API_TOKEN, X-Axiom-Dataset=DATASET_NAME";
-    })
-    .Build();
-```
+    ```csharp
+    Sdk.CreateTracerProviderBuilder()
+        .AddAspNetCoreInstrumentation()
+        .AddHttpClientInstrumentation()
+        .AddOtlpExporter(options =>
+        {
+            options.Endpoint = new Uri("https://AXIOM_DOMAIN/v1/traces");
+            options.Headers = $"Authorization=Bearer API_TOKEN, X-Axiom-Dataset=DATASET_NAME";
+        })
+        .Build();
+    ```
+
+    <Info>
+    <ReplaceDatasetToken />
+    <ReplaceDomain />
+    </Info>
 
 2. Install and configure additional OpenTelemetry instrumentation packages as needed, based on the technologies your application uses. For example, to automatically trace SQL database queries, you might add the corresponding database instrumentation package.
 

guides/opentelemetry-go.mdx

@@ -8,6 +8,7 @@ logoId: 'openTelemetry'
 ---
 
 import ReplaceDatasetToken from "/snippets/replace-dataset-token.mdx"
+import ReplaceDomain from "/snippets/replace-domain.mdx"
 
 OpenTelemetry offers a [single set of APIs and libraries](https://opentelemetry.io/docs/languages/go/instrumentation/) that standardize how you collect and transfer telemetry data. This guide focuses on setting up OpenTelemetry in a Go app to send traces to Axiom.
 
@@ -223,7 +224,7 @@ import (
 const (
    serviceName           = "axiom-go-otel" // Name of the service for tracing.
    serviceVersion        = "0.1.0" // Version of the service.
-   otlpEndpoint          = "api.axiom.co" // OTLP collector endpoint.
+   otlpEndpoint          = "AXIOM_DOMAIN" // OTLP collector endpoint.
    bearerToken           = "Bearer API_TOKEN" // Authorization token.
    deploymentEnvironment = "production" // Deployment environment.
 )
@@ -274,7 +275,10 @@ func InstallExportPipeline(ctx context.Context) (func(context.Context) error, er
 }
 ```
 
+<Info>
 <ReplaceDatasetToken />
+<ReplaceDomain />
+</Info>
 
 ## Run the app