Integrations/AI Logging Guide

AI Logging Guide

A machine-readable endpoint that provides AI coding assistants with everything they need to implement structured logging for LogPulse, including data schema, code examples, OTLP integration, LPQL queries, and best practices.

Overview

The AI Logging Guide is a public API endpoint designed to be consumed by AI coding assistants like Cursor, GitHub Copilot, Windsurf, and Claude. It provides a comprehensive, structured document that teaches AI assistants how to implement LogPulse-compatible structured logging in any application.

By pointing your AI assistant at this endpoint, it gains context about the LogPulse data model, ingest endpoints (REST API and OTLP), recommended attribute patterns, and working code examples, enabling it to generate correct logging code on the first try.

Tip: This endpoint requires no authentication and is publicly available. It is rate-limited to prevent abuse but designed to be fetched by AI tools during coding sessions.

API Endpoint

GEThttps://api.logpulse.io/api/v1/ai/logging-guide

Returns a comprehensive logging integration guide. No API key required. The response is cached with a 1-hour TTL for performance.

Query Parameters

Parameter	Type	Default	Description
language	string	generic	Language for code examples: nodejs, python, go, java, csharp, generic
format	string	markdown	Response format: markdown or json

Language Options

Value	Description	Example URL
nodejs	Node.js / TypeScript: Logger class with batching, Express/Fastify middleware	?language=nodejs
python	Python: Logger class with thread-safe batching, FastAPI middleware	?language=python
go	Go: Logger with goroutine-safe buffering, functional options pattern	?language=go
java	Java 17+: Logger with scheduled flushing, AutoCloseable	?language=java
csharp	C# / .NET 8+: Async logger with IAsyncDisposable	?language=csharp
generic	curl examples for any language: REST API + OTLP	?language=generic

Response Formats

Markdown (default)

Returns the guide as a structured Markdown document. This is the preferred format for AI assistants that support Markdown context (most do).

Example request

GET https://api.logpulse.io/api/v1/ai/logging-guide?language=nodejs

Response: Content-Type: text/markdown; charset=utf-8

JSON

Returns the guide as a structured JSON object with typed fields. Useful for programmatic consumption by custom AI agents or build tools.

Example request

GET https://api.logpulse.io/api/v1/ai/logging-guide?language=nodejs&format=json

Response: Content-Type: application/json; charset=utf-8

The JSON response includes structured sections for endpoints, schema, categories, best practices, query examples, OTLP configuration, and code examples URLs.

What the Guide Covers

The guide provides AI assistants with a complete reference for LogPulse integration:

Data Model

Full log schema with core fields, Kubernetes fields, and the attributes system

Authentication

Bearer token authentication for all ingest endpoints

REST API

POST /api/v1/logs: single and batch log ingestion with examples

OTLP Integration

OTLP Logs + Traces endpoints, severity mapping, K8s metadata, Collector config, SDK env vars

Logging Categories

7 recommended categories with structured attributes: auth, security, http, database, error, business, system

LPQL Queries

Example queries for each category so AI assistants can help users search logs

Code Examples

Production-ready logger classes with batching, retry logic, and convenience methods per language

Best Practices

Do/don't guidelines for structured logging, attribute naming, and security

OTLP Coverage in the Guide

The guide includes a dedicated OTLP section that covers both the logs and traces endpoints. This allows AI assistants to generate OpenTelemetry-compatible configurations and understand how LogPulse processes OTLP data.

OTLP Logs

The guide documents the POST /v1/logs endpoint and explains how LogPulse converts OTLP log records:

Timestamp conversion from nanosecond Unix timestamps to ISO 8601
Severity number mapping (1–4 = trace, 5–8 = debug, 9–12 = info, 13–16 = warn, 17–20 = error, 21+ = fatal)
Automatic Kubernetes metadata extraction from resource attributes
Trace context preservation (traceId, spanId) for log-to-trace correlation
Full OTLP ExportLogsServiceRequest JSON body example

OTLP Traces

The guide documents the POST /v1/traces endpoint and explains how spans are converted to searchable log records:

Span field mapping (traceId, spanId, parentSpanId, kind, status, duration)
HTTP attribute extraction (method, URL, status code)
Service name and operation name mapping
LPQL query examples for traces (error spans, slow spans, trace trees)
Full OTLP ExportTraceServiceRequest JSON body example

Collector & SDK Configuration

The guide includes a production-ready OpenTelemetry Collector configuration for Kubernetes that ships both logs and traces to LogPulse, including k8sattributes processor setup and batch processing. It also documents the universal OTLP SDK environment variables that work across all languages:

OTel SDK environment variables

OTEL_EXPORTER_OTLP_ENDPOINT=https://api.logpulse.io
OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer YOUR_API_KEY"
OTEL_EXPORTER_OTLP_PROTOCOL=http/json

Using with AI Assistants

Each AI assistant has a different mechanism for providing context. Below are setup instructions for the most popular tools.

Cursor

Add the guide URL to your project rules so Cursor has context in every conversation:

.cursor/rules/logpulse.mdc

---
description: LogPulse structured logging integration guide
globs: ["src/**/*.ts", "src/**/*.tsx", "src/**/*.js"]
alwaysApply: false
---

When implementing logging, fetch the LogPulse guide for reference:
https://api.logpulse.io/api/v1/ai/logging-guide?language=nodejs

Follow the schema, attribute conventions, and best practices described in the guide.
Always use the `attributes` field for structured data. All attribute values must be strings.
Use the recommended `category` values: authentication, security, http, database, error, business, system.

GitHub Copilot

Add a custom instruction file to your repository:

.github/copilot-instructions.md

# LogPulse Logging Guide

When implementing logging in this project, refer to the LogPulse AI Logging Guide:
https://api.logpulse.io/api/v1/ai/logging-guide?language=nodejs

Key rules:
- Send logs to POST https://api.logpulse.io/api/v1/logs with Bearer token auth
- Always include `index`, `level`, `source`, and `event` fields
- Use `attributes` for structured metadata (all values must be strings)
- For OpenTelemetry, use OTLP endpoints: POST /v1/logs and POST /v1/traces

Windsurf

Add a global rule or project rule in Windsurf with the guide URL:

.windsurfrules

When implementing logging for this project, use the LogPulse integration guide:
https://api.logpulse.io/api/v1/ai/logging-guide?language=nodejs

Follow all conventions described in the guide including structured attributes,
log categories, and OTLP integration patterns.

Claude (Claude Code / claude.ai)

Add the guide to your project's CLAUDE.md or use it as a prompt:

CLAUDE.md

# Logging

This project uses LogPulse for structured logging.

Integration guide: https://api.logpulse.io/api/v1/ai/logging-guide?language=nodejs
JSON format: https://api.logpulse.io/api/v1/ai/logging-guide?language=nodejs&format=json

When implementing logging, follow the LogPulse guide conventions:
- Use the LogPulseLogger class pattern from the guide
- All attributes must be string values
- Include category, source, and index on every log entry
- For OpenTelemetry: configure OTLP exporters to https://api.logpulse.io

Custom AI Agents

For custom AI agents and automation tools, use the JSON format for programmatic access:

Fetch in your agent

// Fetch the guide as structured JSON
const response = await fetch(
  'https://api.logpulse.io/api/v1/ai/logging-guide?language=nodejs&format=json'
);
const guide = await response.json();

// Use guide.endpoints, guide.schema, guide.categories, guide.otlp, etc.
// to provide context to your AI agent's system prompt

The JSON format includes typed sections for endpoints (REST + OTLP logs + OTLP traces), schema fields, logging categories with recommended attributes, best practices, LPQL query examples, and OTLP configuration including severity mapping, span field mappings, and SDK environment variables.

Rate Limits

Limit	Value
Requests per minute	30
Cache TTL	1 hour (Cache-Control: public, max-age=3600)
Authentication	Not required

Note: The endpoint is rate-limited to 30 requests per minute per IP address. The response includes a Cache-Control header, so AI tools that respect caching will only fetch the guide once per hour.