# OpenTelemetry

> Point an existing OTLP/HTTP trace exporter at Sypnia, with examples for Python, Go, PHP, Rust, Java and the Collector, what each span becomes, and exactly what is ignored at launch.

Applies to: the Sypnia engine (open source, self-hosted) and Sypnia Cloud (paid service). Status: at launch.  
Source: https://docs.sypnia.com/sdks/opentelemetry/

This page is for whoever runs a backend that is not Node: Python, Go, PHP, Rust, Java, or anything else with an OpenTelemetry SDK. Sypnia accepts traces in the OpenTelemetry protocol over HTTP (OTLP/HTTP), on the open-source engine and on Sypnia Cloud alike. Sypnia's own SDKs for these languages are **\[Planned]**; OpenTelemetry is today's answer and stays supported after they exist.

**At the end you will have:** your backend's requests in Sypnia's traces and performance numbers, its exceptions as problems, and its spans joined to the browser's trace when the request came from a page that runs the [browser SDK](https://docs.sypnia.com/sdks/browser).

## The settings, for every language

You change no code that already works. Set the standard OpenTelemetry environment variables:

**Sypnia Cloud**

`.env`

```bash
OTEL_EXPORTER_OTLP_ENDPOINT=https://ingest.sypnia.com/v1/otlp
OTEL_EXPORTER_OTLP_HEADERS=Authorization=Bearer spk_7d1f0c9e4b8a2f6d3c5e1a9b0f4d8c2e
OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
OTEL_TRACES_EXPORTER=otlp
OTEL_METRICS_EXPORTER=none
OTEL_LOGS_EXPORTER=none
OTEL_SERVICE_NAME=shop-api
OTEL_RESOURCE_ATTRIBUTES=deployment.environment.name=production,service.version=4f2a91c
```

**Self-hosted**

`.env`

```bash
OTEL_EXPORTER_OTLP_ENDPOINT=https://sypnia.example.com/v1/otlp
OTEL_EXPORTER_OTLP_HEADERS=Authorization=Bearer spk_7d1f0c9e4b8a2f6d3c5e1a9b0f4d8c2e
OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
OTEL_TRACES_EXPORTER=otlp
OTEL_METRICS_EXPORTER=none
OTEL_LOGS_EXPORTER=none
OTEL_SERVICE_NAME=shop-api
OTEL_RESOURCE_ATTRIBUTES=deployment.environment.name=production,service.version=4f2a91c
```

| Variable                                      | What to put                                          | Why                                                                                                                    |
| --------------------------------------------- | ---------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
| `OTEL_EXPORTER_OTLP_ENDPOINT`                 | Your ingest address followed by `/v1/otlp`.          | The exporter adds `/v1/traces` by itself, so spans go to `…/v1/otlp/v1/traces`.                                        |
| `OTEL_EXPORTER_OTLP_HEADERS`                  | `Authorization=Bearer ` and your ingest key.         | The key says which project the spans belong to. It is public and can only send.                                        |
| `OTEL_EXPORTER_OTLP_PROTOCOL`                 | `http/protobuf`, or `http/json`.                     | Sypnia does not accept gRPC.                                                                                           |
| `OTEL_METRICS_EXPORTER`, `OTEL_LOGS_EXPORTER` | `none`                                               | Sypnia takes traces only. Without this, the exporter keeps trying to send metrics and logs and logs a `404` each time. |
| `OTEL_SERVICE_NAME`                           | A name for this service.                             | It is the name you see on its spans.                                                                                   |
| `OTEL_RESOURCE_ATTRIBUTES`                    | `deployment.environment.name` and `service.version`. | The environment (default `production`) and the release. Use the same values as your frontend.                          |

Use the same project as your frontend: a trace connects parts of one project.

## By language

Each example assumes the variables above are set. Package and command names are the OpenTelemetry project's own; check its documentation for your version.

**Python**

```bash
pip install opentelemetry-distro opentelemetry-exporter-otlp-proto-http
opentelemetry-bootstrap -a install
opentelemetry-instrument python app.py
```

Python reads the header variable strictly: write the space as `%20`.

`.env`

```bash
OTEL_EXPORTER_OTLP_HEADERS=Authorization=Bearer%20spk_7d1f0c9e4b8a2f6d3c5e1a9b0f4d8c2e
```

**Go**

Go has no agent: you create the exporter once, in `main`. It reads the variables above.

`main.go`

```go
package main

import (
	"context"
	"log"
	"net/http"

	"go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp"
	"go.opentelemetry.io/otel"
	"go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracehttp"
	"go.opentelemetry.io/otel/propagation"
	sdktrace "go.opentelemetry.io/otel/sdk/trace"
)

func main() {
	ctx := context.Background()
	exporter, err := otlptracehttp.New(ctx)
	if err != nil {
		log.Fatal(err)
	}
	provider := sdktrace.NewTracerProvider(sdktrace.WithBatcher(exporter))
	defer provider.Shutdown(ctx)
	otel.SetTracerProvider(provider)
	otel.SetTextMapPropagator(propagation.TraceContext{})

	mux := http.NewServeMux()
	mux.HandleFunc("POST /api/checkout", checkout)
	log.Fatal(http.ListenAndServe(":3000", otelhttp.NewHandler(mux, "shop-api")))
}
```

**PHP**

```bash
pecl install opentelemetry
composer require open-telemetry/sdk open-telemetry/exporter-otlp guzzlehttp/guzzle
```

`.env`

```bash
OTEL_PHP_AUTOLOAD_ENABLED=true
```

Then add the auto-instrumentation package of your framework, for example `open-telemetry/opentelemetry-auto-laravel` or `open-telemetry/opentelemetry-auto-symfony`.

**Rust**

`Cargo.toml`

```toml
[dependencies]
opentelemetry = "*"
opentelemetry_sdk = { version = "*", features = ["rt-tokio"] }
opentelemetry-otlp = { version = "*", default-features = false, features = ["trace", "http-proto", "reqwest-client"] }
```

Build the OTLP span exporter with its HTTP transport and install it in a tracer provider with a batch processor. The exporter reads the variables above. The builder's name changed between versions of `opentelemetry-otlp`: follow the example in the crate's documentation for the version you pin, and pin real versions instead of `*`.

**Java**

Download `opentelemetry-javaagent.jar` from the OpenTelemetry project and start your app with it:

```bash
java -javaagent:./opentelemetry-javaagent.jar -jar shop-api.jar
```

**Collector**

If your services already send to an OpenTelemetry Collector, add Sypnia as one more exporter of the traces pipeline:

`otel-collector.yaml`

```yaml
exporters:
  otlphttp/sypnia:
    endpoint: https://ingest.sypnia.com/v1/otlp
    headers:
      Authorization: Bearer spk_7d1f0c9e4b8a2f6d3c5e1a9b0f4d8c2e

service:
  pipelines:
    traces:
      receivers: [otlp]
      processors: [batch]
      exporters: [otlphttp/sypnia]
```

## Check that it works

1. Start your service and call one of its routes.
2. Within 10 minutes the route is listed in Performance with one request, and its trace is in Traces.

To test the address and the key without your app:

```bash
curl -i -X POST "https://ingest.sypnia.com/v1/otlp/v1/traces" \
  -H "Authorization: Bearer spk_7d1f0c9e4b8a2f6d3c5e1a9b0f4d8c2e" \
  -H "Content-Type: application/json" \
  -d '{"resourceSpans":[]}'
```

**You should see:**`HTTP/2 200` and the body `{}`. A `401` means the key is wrong; a `404` means the path is wrong.

## Joining the browser's trace and session

**The trace joins by itself.** The browser SDK sends the W3C `traceparent` header with each call to your API, and OpenTelemetry SDKs read it by default. Your server's spans then carry the browser's trace id. If the API is on another origin than the page, list it in the browser SDK's `traceTargets` and allow the header in CORS: see [Browser](https://docs.sypnia.com/sdks/browser#calls-to-your-api-and-traces).

**The session needs one attribute.** The browser SDK also sends the session's id in the header `x-sypnia-session`. Copy it to the span attribute `session.id` on the server span, and the request appears in that session's timeline:

`app.py`

```python
from flask import Flask, request
from opentelemetry import trace

app = Flask(__name__)

@app.before_request
def link_sypnia_session():
    session_id = request.headers.get("x-sypnia-session")
    if session_id:
        trace.get_current_span().set_attribute("session.id", session_id)
```

Without it the trace is still joined to the browser's call, and through that call to the session; the attribute matters for requests whose browser event was lost.

## What a span becomes

| In OpenTelemetry                                                              | In Sypnia                                                                     |
| ----------------------------------------------------------------------------- | ----------------------------------------------------------------------------- |
| Trace id                                                                      | The trace's id.                                                               |
| Resource `service.name`                                                       | The span's service.                                                           |
| Resource `deployment.environment.name`, or the older `deployment.environment` | The environment. `production` when missing.                                   |
| Resource `service.version`                                                    | The release.                                                                  |
| A span of kind `SERVER` with `http.route`                                     | One request in Performance, and the root of that service's part of the trace. |
| A span of kind `CLIENT` with `db.system.name`                                 | A database call.                                                              |
| A span of kind `CLIENT` with `http.request.method`                            | A call to another service.                                                    |
| Any other span                                                                | An internal step, shown in the trace.                                         |
| Span status `ERROR`, or an `exception` span event                             | A failure. An exception with a stack becomes a server-side problem.           |
| Span attribute `session.id` (32 hex characters)                               | Links the trace to a session.                                                 |

## What Sypnia does not use, at launch

| Sent by OpenTelemetry                                                                     | What happens                                                                                                                                                       |
| ----------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Metrics and logs (`/v1/metrics`, `/v1/logs`)                                              | Not accepted: `404`. Logs and custom metrics are **\[Planned]**.                                                                                                   |
| gRPC transport                                                                            | Not accepted. Use `http/protobuf` or `http/json`.                                                                                                                  |
| Span events other than `exception`                                                        | Dropped.                                                                                                                                                           |
| Span links                                                                                | Dropped.                                                                                                                                                           |
| `tracestate` and baggage                                                                  | Not read and not stored.                                                                                                                                           |
| Attributes whose name contains `authorization`, `cookie`, `password`, `secret` or `token` | Dropped at ingest.                                                                                                                                                 |
| More than 64 attributes on a span, or a value longer than 256 characters                  | The extra attributes are dropped; long values are cut.                                                                                                             |
| More than 500 spans in one trace                                                          | The first 500 are kept; the rest are counted.                                                                                                                      |
| The sampling decision in `traceparent`                                                    | Not used: Sypnia stores what you send. Sample in your SDK or Collector if you send too much.                                                                       |
| The names and e-mails of people                                                           | OpenTelemetry carries none that Sypnia reads. A trace gets its person from its session. See [Identifying people](https://docs.sypnia.com/sdks/identifying-people). |

Limits of one request are in the [API reference](https://docs.sypnia.com/api/otlp): a body of 4,000,000 bytes after decompression and 2,000 spans. The standard batch exporters stay well under both.

## What you do not get this way

OpenTelemetry sends traces. Sessions, replays, clicks and page performance come from the [browser SDK](https://docs.sypnia.com/sdks/browser), which works with any backend. On Sypnia Cloud, a trace counts as one event, however many spans it has.

## Next
