Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs+examples(get started): add trace ingestion examples for nodejs, python, go #4049

Merged
merged 9 commits into from
Oct 15, 2024
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
482 changes: 440 additions & 42 deletions docs/docs/getting-started/configure-trace-ingestion.mdx

Large diffs are not rendered by default.

52 changes: 51 additions & 1 deletion docs/docs/getting-started/create-trace-based-test.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -59,9 +59,23 @@ docker compose up -d --build

- [`https://app.tracetest.io/`](https://app.tracetest.io) - Access the Tracetest Web UI. Sign up and create an organization.
- [`http://localhost:8081`](http://localhost:8081) - The Pokeshop API demo is exposed from Docker to `localhost` on this port.
- `http://api:8081` - To run tests you will use the Docker internal network and the Pokeshop app's service name.
- `http://api:8081` - To run tests you will use the Docker internal network and the service name.
- `http://tracetest-agent:4317` - Trace ingestion URL where Tracetest Agent will accept traces.

<details>
<summary>
<b>Docker Networking</b>
</summary>
Running a test against `localhost` will resolve as `127.0.0.1` inside the Tracetest Agent container.

Add Tracetest Agent to the same network and use service name mapping. *Example: Instead of running an app on `localhost:8080`, add it to your Docker Compose file, connect it to the same network as your Tracetest Agent service, and use `<service-name>:8080` in the URL field when creating a test.*

You can reach services running on your local machine using:

- Linux (Docker version < 20.10.0): `172.17.0.1:8080`
- MacOS (Docker version >= 18.03) and Linux (Docker version >= 20.10.0): `host.docker.internal:8080`
</details>

</TabItem>

<TabItem value="docker-compose" label="Docker Compose">
Expand All @@ -78,6 +92,20 @@ docker compose up -d --build
- `http://api:8081` - To run tests you will use the Docker internal network and the service name.
- `http://tracetest-agent:4317` - Trace ingestion URL where Tracetest Agent will accept traces.

<details>
<summary>
<b>Docker Networking</b>
</summary>
Running a test against `localhost` will resolve as `127.0.0.1` inside the Tracetest Agent container.

Add Tracetest Agent to the same network and use service name mapping. *Example: Instead of running an app on `localhost:8080`, add it to your Docker Compose file, connect it to the same network as your Tracetest Agent service, and use `<service-name>:8080` in the URL field when creating a test.*

You can reach services running on your local machine using:

- Linux (Docker version < 20.10.0): `172.17.0.1:8080`
- MacOS (Docker version >= 18.03) and Linux (Docker version >= 20.10.0): `host.docker.internal:8080`
</details>

</TabItem>

<TabItem value="kubernetes" label="Kubernetes">
Expand All @@ -100,6 +128,16 @@ kubectl port-forward svc/api 8081:8081
- `http://api.default.svc.cluster.local:8081` - To run tests you will use the Kubernetes internal network and the service name.
- `http://tracetest-agent.default.svc.cluster.local:4317` - Trace ingestion URL where Tracetest Agent will accept traces.

<details>
<summary>
<b>Kubernetes Networking</b>
</summary>
Make sure to use the correct `<service-name>` if you edit the Tracetest Agent `service` name.

Running a test against `localhost` will resolve as `127.0.0.1` inside the Tracetest Agent container.
Make sure to run tests using the internal Kubernetes service networking eg: `http://<your-app-service-name>.default.svc.cluster.local:port`.
</details>

</TabItem>

<TabItem value="helm" label="Helm">
Expand All @@ -123,6 +161,18 @@ kubectl port-forward svc/pokeshop-pokemon-api 8081:8081
- `http://pokeshop-pokemon-api:8081` - To run tests you will use the Kubernetes internal network and the service name.
- `http://agent-tracetest-agent:4317` - Trace ingestion URL where Tracetest Agent will accept traces.

<details>
<summary>
<b>Kubernetes Networking</b>
</summary>
Make sure to use the correct `<service-name>` if you edit the Tracetest Agent Helm chart `<release-name>` name.

Running a test against `localhost` will resolve as `127.0.0.1` inside the Tracetest Agent container.
Make sure to run tests using the internal Kubernetes service networking eg: `http://<your-app-service-name>.default.svc.cluster.local:port`.

In the following example you can use: `http://pokeshop-pokemon-api:8081`.
</details>

</TabItem>

</Tabs>
Expand Down
115 changes: 0 additions & 115 deletions docs/docs/getting-started/no-otel.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -44,121 +44,6 @@ Below we provide quick links to all key docs and samples.
| **Python** | https://opentelemetry.io/docs/zero-code/python/ |
| **Go** | https://opentelemetry.io/docs/zero-code/go/ |

</TabItem>
<TabItem value="opentelemetry-operator" label="OpenTelemetry Operator (No Code Changes)" default>

You can install the OpenTelemetry Operator in any existing Kubernetes environment in under 5 minutes by running the following set of commands.

## 1. Install [`cert-manager`](https://cert-manager.io/)
#### This is required for the OpenTelemetry Operator to work.

```bash
kubectl apply -f https://github.com/cert-manager/cert-manager/releases/download/v1.11.0/cert-manager.yaml
```

## 2. Install the [OpenTelemetry Operator](https://opentelemetry.io/docs/k8s-operator/)
#### Traces will be generated and collected automatically.

```bash
kubectl apply -f https://github.com/open-telemetry/opentelemetry-operator/releases/latest/download/opentelemetry-operator.yaml
```

## 3. Create a file named `otel-collector.yaml` for the OpenTelemetry config

```yaml title="otel-collector.yaml"
apiVersion: opentelemetry.io/v1alpha1
kind: Instrumentation
metadata:
name: otel-instrumentation
spec:
exporter:
endpoint: http://otel-collector:4317
propagators:
- tracecontext
- baggage
- b3

---
apiVersion: opentelemetry.io/v1alpha1
kind: OpenTelemetryCollector
metadata:
name: otel
spec:
config: |
receivers:
otlp:
protocols:
grpc:
http:
processors:
batch:
timeout: 100ms
exporters:
otlp/tracetest:
endpoint: tracetest:4317
tls:
insecure: true
service:
pipelines:
traces:
receivers: [otlp]
processors: [batch]
exporters: [otlp/tracetest]
```

You configure 2 separate things:

#### 1. The Instrumentation, which is an init-container that will run on any pod you explictly mark (see step 5).

#### 2. The OpenTelemetry collector, which will collect the traces from the init-container and send them to Tracetest, and/or your trace data store.

What's amazing here is that you can add other exporters to this config file to [send the traces to other services as explained here](../configuration/overview.mdx).

## 4. Apply the `otel-collector.yaml` config file

```bash title="Terminal"
kubectl apply -f otel-collector.yaml
```

## 5. Update any service you want to instrument

Use the [following annotations as seen in the OpenTelemetry docs](https://opentelemetry.io/docs/k8s-operator/automatic/):

- **.NET**: `instrumentation.opentelemetry.io/inject-dotnet: "true"`
- **Java**: `instrumentation.opentelemetry.io/inject-java: "true"`
- **Node.js**: `instrumentation.opentelemetry.io/inject-nodejs: "true"`
- **Python**: `instrumentation.opentelemetry.io/inject-python: "true"`

:::note
Add an environment variable named `SERVICE_NAME` to your service so that you can
later identify it in the tests.
:::

```yaml
apiVersion: apps/v1
kind: Deployment
metadata:
name: your-service
spec:
replicas: 1
template:
annotations:
instrumentation.opentelemetry.io/inject-nodejs: 'true'
spec:
containers:
var:
- name: SERVICE_NAME
value: 'your-service'
```

This will automatically instrument your service with OpenTelemetry and send the traces to the OpenTelemetry collector.

Apply the changes and you're ready! You can start writing integration and end-to-end tests with trace-based testing!

:::note
Check the [official OpenTelemetry docs](https://opentelemetry.io/docs/k8s-operator/automatic/) explaining how to use the OpenTelemetry Operator.
:::

</TabItem>

<TabItem value="auto-instrumentation" label="Auto Instrumentation" default>
Expand Down
Loading
Loading