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

# Contributing

> Contribute to Untrace and run it locally

<Info>
  **Prerequisites**:

  * Node.js (version 18 or higher)
  * Git
  * An LLM provider account (OpenAI, Anthropic, etc.) for testing
</Info>

## Local Development Setup

### Clone the Repository

First, clone the Untrace repository and install dependencies:

<CodeGroup>
  ```bash npm theme={null}
  git clone https://github.com/untrace-dev/untrace.git
  cd untrace
  npm install
  ```

  ```bash yarn theme={null}
  git clone https://github.com/untrace-dev/untrace.git
  cd untrace
  yarn install
  ```

  ```bash pnpm theme={null}
  git clone https://github.com/untrace-dev/untrace.git
  cd untrace
  pnpm install
  ```
</CodeGroup>

### Start the Development Server

Run the development server locally:

```bash theme={null}
npm run dev
```

This will start:

* The API server on port 3000
* The web dashboard on port 3001
* The trace processing service on port 3002

## Project Structure

```plaintext theme={null}
untrace-sdk/
├── packages/
│   ├── analytics/    # Analytics components
│   ├── destinations/ # Integration destinations
│   ├── logger/       # Logging utilities
│   ├── ui/          # UI components
│   └── utils/       # Shared utilities
├── sdks/            # Language-specific SDKs
│   ├── js/          # JavaScript/TypeScript SDK
│   ├── python/      # Python SDK
│   ├── go/          # Go SDK
│   ├── rust/        # Rust SDK
│   ├── csharp/      # C#/.NET SDK
│   └── elixir/      # Elixir SDK
├── docs/            # Documentation
└── examples/        # Example integrations
```

## Development Workflow

### Running Tests

We use Jest for testing. Run the test suite with:

```bash theme={null}
# Run all tests
npm test

# Run tests in watch mode
npm test -- --watch

# Run tests for a specific package
npm test -- packages/analytics
```

### Linting and Formatting

We use ESLint and Prettier to maintain code quality:

```bash theme={null}
# Run linter
npm run lint

# Fix linting issues
npm run lint:fix

# Format code
npm run format
```

## Building Locally

To build all packages:

```bash theme={null}
npm run build
```

To build a specific package:

```bash theme={null}
npm run build --workspace=@untrace/analytics
```

## Running Examples

We provide example integrations in the `examples/` directory. To run an example:

```bash theme={null}
# Navigate to an example
cd examples/basic-usage

# Install dependencies
npm install

# Start the example
npm run dev
```

## Debugging

### SDK Debugging

Run the SDK with debug logging:

```bash theme={null}
# Using npm
npm run dev:sdk -- --debug

# Direct binary
./packages/analytics/bin/run --debug
```

### Dashboard Debugging

The dashboard includes React Developer Tools and runs in development mode by default:

```bash theme={null}
# Start dashboard in development mode
npm run dev:dashboard
```

## Common Issues

<AccordionGroup>
  <Accordion title="Error: Port already in use">
    If port 3000, 3001, or 3002 is already in use, you can specify different ports:

    ```bash theme={null}
    # For API server
    PORT=4000 npm run dev:api

    # For dashboard
    PORT=4001 npm run dev:dashboard

    # For trace service
    TRACE_PORT=4002 npm run dev:service
    ```
  </Accordion>

  <Accordion title="Error: Invalid API Key">
    During development, you can use test API keys:

    ```bash theme={null}
    # Test mode
    UNTRACE_API_KEY=test_key npm run dev
    ```
  </Accordion>
</AccordionGroup>

## Contributing

We welcome contributions! Here's how you can help:

1. Fork the repository
2. Create a feature branch: `git checkout -b feature/amazing-feature`
3. Make your changes
4. Run tests: `npm test`
5. Commit your changes: `git commit -m 'Add amazing feature'`
6. Push to your branch: `git push origin feature/amazing-feature`
7. Open a Pull Request

### Contribution Guidelines

* Follow the existing code style
* Add tests for new features
* Update documentation for changes
* Keep commits focused and atomic
* Write clear commit messages

## Next Steps

<CardGroup>
  <Card title="Architecture" icon="diagram-project" href="/architecture">
    Learn about Untrace's internal architecture
  </Card>

  <Card title="API Reference" icon="code" href="/api-reference">
    Explore the internal APIs
  </Card>

  <Card title="Testing Guide" icon="vial" href="/testing">
    Learn how to test your changes
  </Card>

  <Card title="SDK Development" icon="code" href="/sdk">
    Create integrations for new programming languages
  </Card>
</CardGroup>