Implementation:Helicone Helicone LogController LogRequests

Knowledge Sources	Helicone
Domains	LLM Observability, Log Processing, Handler Chain
Last Updated	2026-02-14 00:00 GMT

Overview

Concrete TSOA controller endpoint for consuming queued log messages in the Jawn backend, provided by the LogController class.

Description

LogController.logRequests is a TSOA-decorated POST endpoint at /v1/log/request that serves as the HTTP entry point for the log processing pipeline. It is called either by the queue consumer infrastructure or directly via the HTTP fallback path from the HeliconeProducer when the queue is unavailable.

The method accepts a KafkaMessageContents body containing the authorization token, Helicone metadata, and the request/response log data. It first validates the heliconeManualAccessKey against the server environment to prevent unauthorized direct access. It then delegates to LogManager.processLogEntry, which constructs the full handler chain:

AuthenticationHandler -> RateLimitHandler -> S3ReaderHandler -> RequestBodyHandler -> ResponseBodyHandler -> PromptHandler -> OnlineEvalHandler -> StripeIntegrationHandler -> LoggingHandler -> PostHogHandler -> LytixHandler -> WebhookHandler -> SegmentLogHandler -> StripeLogHandler

Each handler in this chain processes the message through a shared HandlerContext and passes control to the next handler.

Usage

This endpoint is not typically called directly by end users. It is invoked by the Kafka/SQS consumer or by the worker's HTTP fallback path. It is secured with the api_key security scheme via TSOA.

Code Reference

Source Location

• Repository: Helicone
• File: valhalla/jawn/src/controllers/private/logController.ts (lines 6-37)

Signature

@Route("v1/log")
@Tags("Log")
@Security("api_key")
export class LogController extends Controller {
  @Post("/request")
  public async logRequests(
    @Body() logMessage: KafkaMessageContents,
    @Request() request: JawnAuthenticatedRequest
  ): Promise<void>
}

Import

import { LogController } from "../../controllers/private/logController";

I/O Contract

Inputs

Name	Type	Required	Description
logMessage	KafkaMessageContents	Yes	The structured log message containing: authorization (string) -- The Helicone auth token. heliconeMeta (HeliconeMeta) -- Processing directives (model override, omit flags, webhook toggle, prompt metadata, gateway metadata, billing flags). log (Log) -- The request/response data including IDs, user ID, properties, provider, target URL, body sizes, timestamps, streaming flag, status, token counts, latency, and cost.
request	JawnAuthenticatedRequest	Yes	The authenticated Express request object injected by TSOA, carrying the resolved auth context.

Outputs

Name	Type	Description
(void)	Promise<void>	Returns void. Sets HTTP status 200 on success, 401 if the manual access key is invalid, or 500 if the log processing pipeline throws an error.

Usage Examples

Basic Usage

// This endpoint is typically called via HTTP by the queue consumer or fallback:
const response = await fetch("https://jawn.helicone.ai/v1/log/request", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": authorization,
  },
  body: JSON.stringify({
    log: {
      request: {
        id: "req-uuid",
        userId: "user-123",
        properties: {},
        targetUrl: "https://api.openai.com/v1/chat/completions",
        provider: "OPENAI",
        bodySize: 512,
        path: "/v1/chat/completions",
        requestCreatedAt: new Date(),
        isStream: false,
      },
      response: {
        id: "resp-uuid",
        status: 200,
        bodySize: 1024,
        responseCreatedAt: new Date(),
        delayMs: 250,
      },
    },
    authorization: "Bearer sk-helicone-...",
    heliconeMeta: {
      omitRequestLog: false,
      omitResponseLog: false,
      webhookEnabled: false,
    },
  }),
});

Related Pages

Implements Principle

• Principle:Helicone_Helicone_Backend_Log_Processing

Requires Environment

• Environment:Helicone_Helicone_Node_20_TypeScript_Runtime