Merge branch 'main' of github.com:Baselime/docs

sending-data/languages/go.md

@@ -9,17 +9,14 @@ The [Baselime Go OpenTelemetry SDK](https://github.com/baselime/go-opentelemetry
 
 This SDK uses [OpenTelemetry for Go](https://opentelemetry.io/docs/instrumentation/go/) and provides a layer that facilitates instrumenting your Go applications.
 
-!!!
-If your application is already instrumented with [OpenTelemetry](https://opentelemetry.io/), you can start sending your tracing data to Baselime without any additional code changes.
-
-Add the Baselime OpenTelemetry endpoint to your exporter:
-- Endpoint `https://otel.baselime.io/v1/`
-- Header: `x-api-key: <BASELIME_API_KEY>` 
-!!!
-
 ---
 
 ## Instrumentation
+!!!info
+Is your application already instrumented with [OpenTelemetry](https://opentelemetry.io/)?
+
+[!ref icon="../../assets/images/logos/logo_open_telemetry.png" text="Configure endpoint and headers"](../platforms/opentelemetry/opentelemetry.md#configuration)
+!!!
 
 ### Step 1: Install the SDKs
 
@@ -29,32 +26,64 @@ Install the [Baselime Go OpenTelemetry SDK](https://github.com/baselime/go-opent
 go get github.com/baselime/go-opentelemetry
 ```
 
-### Step 2: Set the Baselime environment variables
+### Step 2: Add the OpenTelemetry Instrumentation to your application
 
-Set the environment variables of your comntainer service to include the Baselime API Key
+```go # :icon-code: main.go
+package main
 
-```bash # :icon-terminal: terminal
-export BASELIME_API_KEY=<YOUR_API_KEY>
-export OTEL_SERVICE_NAME='<NAME_OF_YOUR_APP_OR_SERVICE>'
-```
+import (
+	"context"
+	baselime_opentelemetry "github.com/baselime/go-opentelemetry"
+	"go.opentelemetry.io/otel"
+	"go.opentelemetry.io/otel/attribute"
+	otelMetric "go.opentelemetry.io/otel/metric"
+	"log"
+	"net/http"
+	"os"
+)
 
-### Step 3: Add the Opentelemetry Instrumentation to your application
+// Example tracer and counter
+var tracer = otel.Tracer("flyio_tracer")
+var reqCounter, _ = otel.Meter("your_service_name").Int64Counter("http.request")
 
-```go # :icon-terminal: terminal
 func main() {
-    params := baselime_opentelemetry.Config{}
-    otelShutdown, err := baselime_opentelemetry.ConfigureOpenTelemetry(params)
-
-    if err != nil {
-        log.Fatalf("error setting up OTel SDK - %e", err)
-    }
+	// Initialise Baselime OTEL distro
+	params := baselime_opentelemetry.Config{}
+	otelShutdown, err := baselime_opentelemetry.ConfigureOpenTelemetry(params)
+	if err != nil {
+		log.Fatalf("error setting up OTel SDK - %e", err)
+	}
+	defer otelShutdown()
+
+	http.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) {
+		// Create new span for each request
+		ctx, span := tracer.Start(r.Context(), "request-received")
+		defer span.End()
+
+		// Increment counter on each request, with path as an attribute
+		reqCounter.Add(r.Context(), 1, otelMetric.WithAttributes(
+			attribute.String("path", r.URL.Path),
+		))
+
+		// Step into function and produce nested span
+		someCustomFunction(ctx)
+	})
+	log.Fatal(http.ListenAndServe(":"+port, nil))
+}
 
-    defer otelShutdown()
-    ...
+// A function that produces its own span
+func someCustomFunction(ctx context.Context) {
+	ctx, span := tracer.Start(ctx, "get-data-environments")
+	defer span.End()
 }
 ```
 
-Once these steps are completed, distributed traces from your go container applications should be available in Baselime to query via the console or the Baselime CLI.
+### Step 3: Run your application
+Now your Go application is instrumented with OpenTelemetry and will send traces and metrics to Baselime.
+```shell # :icon-terminal: terminal
+BASELIME_API_KEY=your_api_key go run main.go
+```
+![Traces in console.baselime.io](../../assets/images/illustrations/sending-data/flyio_traces.png)
 
 ---
 
@@ -79,13 +108,24 @@ In Go you have to manually instrument the libraries you use. You can find instru
 
 Once you have installed the instrumentation you can find the instructions on how to apply it in their github repo, each instrumentation could be slightly different.
 
-```go # :icon-terminal: terminal
-// init aws config
-cfg, err := awsConfig.LoadDefaultConfig(ctx)
-if err != nil {
-    panic("configuration error, " + err.Error())
-}
+```go # :icon-code: main.go
+package main
+
+import (
+	"context"
+	"github.com/aws/aws-sdk-go-v2/aws"
+	"go.opentelemetry.io/contrib/instrumentation/github.com/aws/aws-sdk-go-v2/otelaws"
+)
 
-// instrument all aws clients
-otelaws.AppendMiddlewares(&cfg.APIOptions)
-    ```
+func main() {
+
+	// init aws config
+	cfg, err := aws.LoadDefaultConfig(context.TODO())
+	if err != nil {
+		panic("configuration error, " + err.Error())
+	}
+
+	// instrument all aws clients
+	otelaws.AppendMiddlewares(&cfg.APIOptions)
+}
+```

sending-data/languages/node.js.md

@@ -9,17 +9,14 @@ The [Baselime Node.js OpenTelemetry SDK](https://github.com/baselime/node-opente
 
 This SDK uses [OpenTelemetry for JavaScript](https://opentelemetry.io/docs/instrumentation/js/) and provides a layer that facilitates instrumenting your Node.js applications.
 
-!!!
-If your application is already instrumented with [OpenTelemetry](https://opentelemetry.io/), you can start sending your tracing data to Baselime without any additional code changes.
-
-Add the Baselime OpenTelemetry endpoint to your exporter:
-- Endpoint `https://otel.baselime.io/v1/`
-- Header: `x-api-key: <BASELIME_API_KEY>` 
-!!!
-
 ---
 
 ## Instrumentation
+!!!info
+Is your application already instrumented with [OpenTelemetry](https://opentelemetry.io/)?
+
+[!ref icon="../../assets/images/logos/logo_open_telemetry.png" text="Configure endpoint and headers"](../platforms/opentelemetry/opentelemetry.md#configuration)
+!!!
 
 ### Step 1: Install the SDKs
 
@@ -35,10 +32,10 @@ npm i --save \
 
 Create a `tracing.js` file
 
-``` javascript # :icon-code: src/tracing.js
+``` typescript # :icon-code: src/tracing.js
 const { BaselimeSDK } = require('@baselime/node-opentelemetry');
 const { getNodeAutoInstrumentations } = require('@opentelemetry/auto-instrumentations-node');
-
+import opentelemetry from '@opentelemetry/api';
 
 const sdk = new BaselimeSDK({
   instrumentations: [
@@ -47,6 +44,27 @@ const sdk = new BaselimeSDK({
 });
 
 sdk.start();
+
+// Get tracer
+const tracer = opentelemetry.trace.getTracer('example-basic-tracer-node');
+
+//Create a span
+const parentSpan = tracer.startSpan('main');
+parentSpan.end();
+
+// Create meter
+const meter = opentelemetry.metrics.getMeter(
+  'instrumentation-scope-name',
+  'instrumentation-scope-version',
+);
+
+// Create a counter
+const counter = meter.createCounter('my-counter');
+counter.add(1);
+
+// Create a gauge
+const gauge = meter.createUpDownCounter('events.counter');
+counter.add(1);
 ```
 
 ### Step 3: Set the Baselime environment variables

sending-data/languages/python.md

@@ -9,17 +9,14 @@ The [Baselime Python OpenTelemetry SDK](https://github.com/baselime/python-opent
 
 This SDK uses [OpenTelemetry for Python](https://opentelemetry.io/docs/instrumentation/python/) and provides a layer that facilitates instrumenting your Python applications.
 
-!!!
-If your application is already instrumented with [OpenTelemetry](https://opentelemetry.io/), you can start sending your tracing data to Baselime without any additional code changes.
-
-Add the Baselime OpenTelemetry endpoint to your exporter:
-- Endpoint `https://otel.baselime.io/v1/`
-- Header: `x-api-key: <BASELIME_API_KEY>` 
-!!!
-
 ---
 
 ## Instrumentation
+!!!info
+Is your application already instrumented with [OpenTelemetry](https://opentelemetry.io/)?
+
+[!ref icon="../../assets/images/logos/logo_open_telemetry.png" text="Configure endpoint and headers"](../platforms/opentelemetry/opentelemetry.md#configuration)
+!!!
 
 ### Step 1: Install the SDKs
 

sending-data/platforms/opentelemetry/opentelemetry.md

@@ -5,29 +5,27 @@ order: -4
 
 If your codebase is already instrumented with [OpenTelemetry](https://opentelemetry.io/), you can start sending your traces, metrics and logs to Baselime today.
 
-**Step 1:** Get `BASELIME_API_KEY` from the [Baselime console](https://console.baselime.io).
 
-**Step 2:** Set the headers
+## Configuration
+
+### Endpoint
+* HTTP: `otel.baselime.io/v1/`
+* gRPC: `otel-ingest.baselime.io:4317`
+
+### Headers
 ```yaml
 x-api-key: <BASELIME_API_KEY>
-x-baselime-dataset: <YOUR_DATASET>
+x-baselime-dataset: <YOUR_DATASET> # Optional, defaults to "otel"
 ```
 
-**Step 3:** Set exporter endpoint
-+++HTTP
-- Endpoint `otel.baselime.io/v1/`
-+++gRPC
-- Endpoint `otel-ingest.baselime.io:4317`
-+++
-
 ---
-## Baselime Opentelemetry for Platforms
+## Baselime OpenTelemetry for Platforms
 [!ref icon="../../../assets/images/logos/logo_aws_lambda.png"](../../platforms/aws/aws-lambda/traces/index.md)
 [!ref icon="../../../assets/images/logos/cloudflare.png"](../../platforms/cloudflare/traces.md)
 
 ---
 
-## Baselime Opentelemetry Distros
+## Baselime OpenTelemetry Distros
 [!ref icon="../../../assets/images/logos/node.svg"](../../languages/node.js.md)
 [!ref icon="../../../assets/images/logos/next.js.svg"](../../languages/next.js.md)
 [!ref icon="../../../assets/images/logos/python.svg"](../../languages/python.md)
@@ -40,5 +38,109 @@ x-baselime-dataset: <YOUR_DATASET>
 Baselime supports [AWS PrivateLink](https://aws.amazon.com/privatelink/) for OpenTelemetry.
 [!ref icon="../../../assets/images/logos/aws.svg"](./private-link.md)
 
-## Language APIs and SDKs
-Consult the [OTEL documentation](https://opentelemetry.io/docs/languages/) to find support for traces, metrics and logs for your languages
+---
+
+## Manual instrumentation
+
+This section covers basic configuration of traces and metrics exporter. For more detailed examples, refer to the
+[OpenTelemetry Distros](#baselime-opentelemetry-distros) section for your language or platform.
+
+==- Javascript
+```javascript # :icon-code: index.js
+import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-http';
+import { OTLPMetricExporter } from '@opentelemetry/exporter-metric-otlp-http';
+
+const traceExporter = new OTLPTraceExporter({
+    url: "otel.baselime.cc:4317",
+    headers: {
+        "x-api-key": BASELIME_API_KEY,
+        "x-baselime-dataset": YOUR_DATASET,
+    },
+    timeoutMillis: 1000,
+});
+
+const metricExporter = new OTLPMetricExporter({
+    url: "otel.baselime.cc:4317",
+    headers: {
+        "x-api-key": BASELIME_API_KEY,
+        "x-baselime-dataset": YOUR_DATASET,
+    },
+    timeoutMillis: 1000,
+});
+```
+
+[OpenTelemetry documentation for Javascript](https://opentelemetry.io/docs/languages/js/exporters/#available-exporters)
+
+==- Go
+```go # :icon-code: main.go
+package main
+
+import (
+	"context"
+	"go.opentelemetry.io/otel/exporters/otlp/otlpmetric/otlpmetricgrpc"
+	"go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracegrpc"
+)
+
+var metricExporter, _ = otlpmetricgrpc.New(
+	context.TODO(),
+	otlpmetricgrpc.WithEndpoint("otel-ingest.baselime.cc:4317"),
+	otlpmetricgrpc.WithHeaders(map[string]string{
+		"x-api-key": BASELIME_API_KEY,
+		"x-baselime-dataset": YOUR_DATASET,
+	}),
+)
+
+var traceExporter, _ = otlptracegrpc.New(
+	context.TODO(),
+	otlptracegrpc.WithEndpoint("otel-ingest.baselime.cc:4317"),
+	otlptracegrpc.WithHeaders(map[string]string{
+        "x-api-key": BASELIME_API_KEY,
+        "x-baselime-dataset": YOUR_DATASET,
+    }),
+)
+```
+[OpenTelemetry documentation for Go](https://opentelemetry.io/docs/languages/go/exporters/#otlp-traces-over-grpc)
+
+==- Python
+```python # :icon-code: main.py
+from opentelemetry.exporter.otlp.proto.grpc.trace_exporter import OTLPSpanExporter
+from opentelemetry.exporter.otlp.proto.grpc.metrics_exporter import OTLPMetricsExporter
+
+span_exporter = OTLPSpanExporter(
+    endpoint="otel-ingest.baselime.cc:4317",
+    headers={
+        "x-api-key": BASELIME_API_KEY,
+        "x-baselime-dataset": YOUR_DATASET,
+    },
+)
+
+metric_exporter = OTLPMetricsExporter(
+    endpoint="otel-ingest.baselime.cc:4317",
+    headers={
+        "x-api-key": BASELIME_API_KEY,
+        "x-baselime-dataset": YOUR_DATASET,
+    },
+)
+```
+[OpenTelemetry documentation for Python](https://opentelemetry.io/docs/languages/python/exporters/#usage)
+==- Java
+```java # :icon-code: Main.java
+import io.opentelemetry.exporter.otlp.metrics.OtlpGrpcMetricExporter;
+import io.opentelemetry.exporter.otlp.trace.OtlpGrpcSpanExporter;
+
+OtlpGrpcSpanExporter spanExporter = OtlpGrpcSpanExporter.builder()
+    .setEndpoint("otel-ingest.baselime.cc:4317")
+    .addHeader("x-api-key", BASELIME_API_KEY)
+    .addHeader("x-baselime-dataset", YOUR_DATASET)
+    .build();
+
+OtlpGrpcMetricExporter metricExporter = OtlpGrpcMetricExporter.builder()
+    .setEndpoint("otel-ingest.baselime.cc:4317")
+    .addHeader("x-api-key", BASELIME_API_KEY)
+    .addHeader("x-baselime-dataset", YOUR_DATASET)
+    .build();
+```
+[OpenTelemetry documentation for Java](https://opentelemetry.io/docs/languages/java/exporters/)
+==- Other
+Consult the [OTEL documentation](https://opentelemetry.io/docs/languages/) to find support for traces, metrics and logs for other languages and platforms.
+==-