> ## Documentation Index
> Fetch the complete documentation index at: https://docs.aiaxoniq.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Onboarding: developer

> One engineer, one service, working this afternoon — the shortest honest path from nothing to traces, logs and metrics you can use.

You are one engineer with one service and you want this working today. No
rollout plan, no Kubernetes, no committee.

<Info>
  **About an hour.** Ten minutes of it is proving the pipeline works; the rest
  is instrumenting your service and checking you got it right.
</Info>

## 1. Prove the path before writing any code

Run the [Quickstart](/get-started/quickstart). Ten minutes, `curl` only, one
log record.

<Note>
  **Do not skip this because it looks trivial.** It separates "my
  instrumentation is wrong" from "my network, key or endpoint is wrong", and
  those two look identical from inside your application. Everything after this
  point is your code.
</Note>

## 2. Instrument your service

Auto-instrumentation, which needs no code changes in most languages —
frameworks, HTTP clients and database drivers are covered automatically.

```bash theme={null}
export OTEL_SERVICE_NAME=my-service
export OTEL_RESOURCE_ATTRIBUTES=deployment.environment=development
export OTEL_EXPORTER_OTLP_ENDPOINT="$OIQ_ENDPOINT"
export OTEL_EXPORTER_OTLP_HEADERS="X-License-Key=$OIQ_LICENSE_KEY"
```

Language-specific setup is on
[Instrument your application](/send-data/otel/zero-code).

<Warning>
  **`OTEL_EXPORTER_OTLP_ENDPOINT` is the base URL.** The SDK appends
  `/v1/traces` itself, so an endpoint that already ends in a signal path
  produces a `404` that reads as though the endpoint were wrong.
</Warning>

## 3. Generate traffic and look

Exercise your service, wait about ten seconds, then check three things:

<Steps>
  <Step title="Services">
    Your service is listed, under the name you chose. If you see
    `unknown_service`, `OTEL_SERVICE_NAME` did not reach the process.
  </Step>

  <Step title="Traces">
    Open one. You should see a span for the inbound request and a child span
    per outbound call or query.
  </Step>

  <Step title="Logs">
    Search for your service:

    ```text theme={null}
    service.name:"my-service"
    ```
  </Step>
</Steps>

<Note>
  **Ten seconds, not instantly.** Ingest acknowledges before storage, and a
  batching consumer flushes at 50,000 rows or five seconds. On a quiet
  development account you are always waiting out the five seconds.
</Note>

## 4. Connect your logs to your traces

This is the step that makes the tool genuinely useful, and the one most people
skip.

<Warning>
  **A `print()` or a bare file logger produces log lines that are correct,
  searchable, and permanently disconnected from every trace.** You will not get
  an error — you will get an empty "logs for this span" panel and assume the
  feature is broken.

  Use your language's OpenTelemetry logging bridge. See
  [Sending logs as well as traces](/send-data/otel/zero-code#sending-logs-as-well-as-traces).
</Warning>

Once connected: click a slow span, see the log lines written during it. That is
the whole value proposition, and it is one configuration change away.

## 5. Add spans where you actually have questions

Auto-instrumentation stops at your framework's boundary. If the interesting
work is inside a function, add a span around it — but not around everything.

<Warning>
  **Do not instrument every function.** A span per function produces traces
  hundreds of spans deep that nobody reads and that cost real money to store.

  A span is worth it when the operation could be slow, could fail on its own,
  or is a unit you would want timed separately. See
  [Manual instrumentation](/send-data/otel/manual-instrumentation).
</Warning>

## Working locally

Point your local service at aiAxonIQ directly. It works, and it is the fastest
way to iterate on instrumentation.

<Warning>
  **Tag it as development.** Set `deployment.environment=development` so local
  runs do not sit alongside production in every chart and trip every alert.
  This is one environment variable and it saves an afternoon of confusion
  later.
</Warning>

## Troubleshooting, in likelihood order

| Symptom                          | Usually                                                                            |
| :------------------------------- | :--------------------------------------------------------------------------------- |
| Nothing at all                   | The time range. Narrow to 15 minutes.                                              |
| `unknown_service`                | `OTEL_SERVICE_NAME` did not reach the process — check it is exported, not just set |
| `401`                            | Wrong header name, or a revoked key. It is `X-License-Key`.                        |
| `404`                            | The endpoint has a signal path on it; use the base URL                             |
| Traces but no logs               | No trace-aware logging bridge — step 4                                             |
| Works locally, not on the server | Egress. Run the health check *from that server*.                                   |

The full version is on [Troubleshooting](/support/troubleshooting).

## When you are ready for more

<CardGroup cols={3}>
  <Card title="Take it to your team" icon="users" href="/onboarding/saas">
    The full journey: environments, alerting, dashboards, roles.
  </Card>

  <Card title="Searching logs" icon="magnifying-glass" href="/guides/logs/search">
    The query syntax, including the numeric comparisons.
  </Card>

  <Card title="API reference" icon="code" href="/api-reference/introduction">
    Everything the product does, programmatically.
  </Card>
</CardGroup>