traceapm/README.md

SDK for OpenTelemetry auto-instrumentation and OTLP export for Node.js apps.

# traceapm

A focused SDK to enable distributed tracing and metrics for your Node.js applications with minimal configuration. Just import, initialize, and go!

## Installation

```sh
npm install traceapm
```

## Usage

Add this at the very top of your application's entry point (e.g., `index.js` or `server.js`):

```js
const { init } = require('traceapm');

init({
  serviceName: 'my-service', // Name of your service
  endpoint: 'http://localhost:4318', // Collector endpoint
  attributes: { 'deployment.environment': 'dev' }, // Optional extra attributes
});
```

## Options
- `serviceName` (string): Name of your service (default: `my-service`)
- `endpoint` (string): Collector endpoint (default: `http://localhost:4318`)
- `attributes` (object): Additional resource attributes (default: `{}`)

## How it works
- Auto-instruments supported Node.js libraries (tracing and metrics)
- Exports traces and metrics to your collector (HTTP or gRPC)
- Supports proxy environments
- Logs important events and errors to both the console and a log file (`traceapm.log`)
- Minimal configuration required

## Logging

traceapm automatically logs important events and errors to both the console and a log file (`traceapm.log`).

### API Hit Logging (Express Middleware)

To log every API hit (method and URL) in your Express app, use the provided middleware:

```js
const express = require('express');
const { init } = require('traceapm');

const { apiLogger } = init({ serviceName: 'my-service' });

const app = express();
app.use(apiLogger); // Logs every API hit

app.get('/', (req, res) => res.send('Hello World!'));

app.listen(3000);
```

All API hits will be logged to both the console and `traceapm.log`.

## Proxy Support

If you need to export traces/metrics through a proxy, use the provided helper:

```js
const { getProxyAgent } = require('traceapm').init({ serviceName: 'my-service' });
const agent = getProxyAgent('http://myproxy:8080');
```

## gRPC Export (Advanced)

A stub for gRPC exporter setup is provided for advanced users who want to export via gRPC:

```js
const { setupGrpcExporter } = require('traceapm').init({ serviceName: 'my-service' });
setupGrpcExporter(); // Extend as needed
```

---

## Contributors: Modular Code Structure

- `src/autoLogger.js` — Auto-logging of API hits (no middleware needed)
- `src/grpcExporter.js` — gRPC exporter stub
- `src/proxy.js` — Proxy support
- `src/init.js` — Main entry point, wires up all features
- `utils/logger.js` — Winston logger utility
- `utils/validate.js` — Config validation

---

## Purpose

**traceapm** is designed to be a focused, modern, and easy-to-use solution for exporting traces and metrics from Node.js applications. Advanced features are modular and can be extended by contributors, but the core package remains simple and reliable for all users.