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

# Quickstart

> Learn how to use Autoblocks tracing in JavaScript/TypeScript applications

## Installation

```bash
npm install @autoblocks/client
```

## Basic Example

Here's a simple example showing how to use tracing with OpenAI:

```typescript
// instrumentation.ts
import { initAutoTracer } from '@autoblocks/client';
import { OpenAIInstrumentation } from '@traceloop/instrumentation-openai';

initAutoTracer({
  apiKey: process.env.AUTOBLOCKS_V2_API_KEY,
  instrumentations: [new OpenAIInstrumentation()],
  isBatchDisabled: true,
});

// app.ts
import './instrumentation';
import { traceApp } from '@autoblocks/client';

const app = async () => {
  // Your application code here
}

const main = async () => {
  await traceApp('doctor-gpt', 'test', app);
};

main();
```

## Advanced Usage

### Creating Spans

You can create custom spans using OpenTelemetry's tracer:

```typescript
import { trace } from '@opentelemetry/api';
import { SpanKind } from '@opentelemetry/api';

const tracer = trace.getTracer('my-tracer');

async function myFunction() {
  const span = tracer.startSpan('my_operation', {
    kind: SpanKind.INTERNAL,
    attributes: {
      custom_attribute: 'value'
    }
  });

  try {
    // Your code here
    span.setAttribute('result', 'success');
  } catch (error) {
    span.recordException(error);
    span.setStatus({ code: SpanStatusCode.ERROR });
    throw error;
  } finally {
    span.end();
  }
}
```

### Error Handling

Record exceptions in spans:

```typescript
try {
  // Your code here
} catch (error) {
  span.recordException(error);
  span.setStatus({ code: SpanStatusCode.ERROR });
  throw error;
}
```

### Adding Attributes

Add attributes to spans for better context:

```typescript
span.setAttribute('model', 'gpt-4');
span.setAttribute('temperature', 0.7);
span.setAttribute('max_tokens', 100);
```

### Nested Spans

Create nested spans to represent complex operations:

```typescript
async function complexOperation() {
  const parentSpan = tracer.startSpan('parent_operation');
  parentSpan.setAttribute('parent_data', 'value');

  try {
    const childSpan = tracer.startSpan('child_operation', {
      parent: parentSpan
    });
    childSpan.setAttribute('child_data', 'value');

    try {
      // Child operation code
    } finally {
      childSpan.end();
    }
  } finally {
    parentSpan.end();
  }
}
```

## Best Practices

1. **Span Naming**
   * Use descriptive names that reflect the operation
   * Follow a consistent naming convention
   * Include the operation type in the name

2. **Attribute Management**
   * Add relevant context to spans
   * Avoid logging sensitive data
   * Use consistent attribute names

3. **Error Handling**
   * Always record exceptions
   * Set appropriate error status
   * Include error details in attributes

4. **Performance**
   * Keep spans focused
   * Avoid excessive attributes
   * Use sampling for high-volume applications

5. **Async Operations**
   * Properly handle async/await with spans
   * Ensure spans are ended in finally blocks
   * Use Promise.all for parallel operations

6. **TypeScript Integration**
   * Use proper types for spans and attributes
   * Leverage TypeScript's type system for safety
   * Document complex types and interfaces

## Additional Resources

### OpenTelemetry

* [OpenTelemetry JavaScript Documentation](https://opentelemetry.io/docs/instrumentation/js/)
* [OpenTelemetry JavaScript API](https://opentelemetry.io/docs/instrumentation/js/api/)

### OpenLLMetry

* [OpenLLMetry JavaScript](https://github.com/traceloop/openllmetry-js)
* [OpenLLMetry JavaScript Documentation](https://traceloop.com/openllmetry)

## Next Steps

* [Python Tracing Guide](/tracing/python)
* [Tracing Overview](/tracing/overview)