POST /api/logs

Ingest error logs into VIJ Admin

The POST /api/logs endpoint receives error logs from vij-sdk or custom clients and stores them in MongoDB.

Request

message · string · required

The error message describing what went wrong.

Example: "TypeError: Cannot read property 'map' of undefined"

name · string · required

The error name or type.

Example: "TypeError", "ReferenceError", "CustomError"

stack · string · required

Full stack trace of the error.

Example:

Error: Payment processing failed
    at processPayment (payment.js:45:12)
    at handleCheckout (checkout.js:123:5)
    at onClick (Button.tsx:67:20)

severity · string · required

Severity level of the error.

Values: "error", "warning", "info"

Default: "error"

timestamp · string · required

ISO 8601 timestamp when the error occurred.

Format: YYYY-MM-DDTHH:mm:ss.sssZ

Example: "2024-01-01T12:34:56.789Z"

appId · string · required

Identifier for the application that generated the error.

Example: "my-frontend-app", "backend-api", "mobile-app"

environment · string · required

Environment where the error occurred.

Example: "production", "staging", "development"

metadata · object

Custom metadata attached to the error.

Example:

{
  "userId": "user-123",
  "userEmail": "[e-mail]",
  "feature": "checkout",
  "orderId": "order-456",
  "version": "2.1.0"
}

context · object

Environmental context (browser or Node.js information).

Browser Context:

{
  "viewport": { "width": 1920, "height": 1080 },
  "screen": { "width": 1920, "height": 1080, "colorDepth": 24 },
  "browser": {
    "userAgent": "Mozilla/5.0...",
    "language": "en-US",
    "platform": "MacIntel"
  },
  "network": {
    "effectiveType": "4g",
    "downlink": 10,
    "rtt": 50
  }
}

Node.js Context:

{
  "process": {
    "pid": 12345,
    "platform": "linux",
    "arch": "x64",
    "nodeVersion": "v20.0.0",
    "memory": {
      "rss": 50000000,
      "heapUsed": 20000000
    }
  }
}

Response

success · boolean

Indicates whether the log was successfully stored.

id · string

MongoDB ObjectId of the created log entry.

group · string

Fingerprint hash used for error grouping.

Example Request

cURL

curl -X POST https://vij.example.com/api/logs \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Payment processing failed",
    "name": "Error",
    "stack": "Error: Payment processing failed\n    at processPayment (payment.js:45:12)",
    "severity": "error",
    "timestamp": "2024-01-01T12:34:56.789Z",
    "appId": "my-app",
    "environment": "production",
    "metadata": {
      "userId": "user-123",
      "orderId": "order-456"
    },
    "context": {
      "viewport": { "width": 1920, "height": 1080 }
    }
  }'

Example Response

Success (200)

{
  "success": true,
  "id": "65a1b2c3d4e5f6g7h8i9j0k1",
  "group": "abc123def456"
}

Error Responses

Bad Request (400)

{
  "error": "Missing required field: message"
}

Validation Rules

Required Fields

All of these fields must be present:

• message
• name
• stack
• severity
• timestamp
• appId
• environment

Optional fields:

• metadata (defaults to {})
• context (defaults to {})

Severity Values

severity must be one of:

• "error" - Critical errors
• "warning" - Non-critical issues
• "info" - Informational logs

Any other value will return a 400 error.

Timestamp Format

timestamp must be a valid ISO 8601 string:

• Format: YYYY-MM-DDTHH:mm:ss.sssZ
• Example: 2024-01-01T12:34:56.789Z
• Must be in UTC (Z timezone)

Invalid formats will return a 400 error.

String Length Limits

• message: Max 10,000 characters
• name: Max 500 characters
• stack: Max 50,000 characters
• appId: Max 100 characters
• environment: Max 50 characters

Exceeding limits will truncate the value.

Rate Limiting

VIJ Admin does not enforce rate limiting by default. However, you should implement rate limiting in production to prevent abuse.

Recommended limits:

• 1,000 requests per minute per IP
• 10,000 requests per hour per appId

Implementation example:

// Add to middleware
import rateLimit from 'express-rate-limit';

const limiter = rateLimit({
  windowMs: 60 * 1000, // 1 minute
  max: 1000,
  message: 'Too many requests'
});

app.use('/api/logs', limiter);

CORS Configuration

VIJ Admin allows all origins by default for the /api/logs endpoint.

Default CORS headers:

Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: POST, OPTIONS
Access-Control-Allow-Headers: Content-Type

Custom CORS (if needed):

// In next.config.js
module.exports = {
  async headers() {
    return [
      {
        source: '/api/logs',
        headers: [
          { key: 'Access-Control-Allow-Origin', value: 'https://your-app.com' },
          { key: 'Access-Control-Allow-Methods', value: 'POST, OPTIONS' },
          { key: 'Access-Control-Allow-Headers', value: 'Content-Type' }
        ]
      }
    ];
  }
};

Processing Pipeline

When a log is received, VIJ processes it through these steps:

1. Validation - Check required fields and formats
2. Fingerprinting - Generate error group fingerprint
3. Storage - Insert into MongoDB logs collection
4. Indexing - Update MongoDB indexes
5. Grouping - Update error group counters
6. Response - Return success with log ID

Processing time: Typically < 50ms

Batch Logging

Send multiple logs in a single request:

POST /api/logs/batch

{
  "logs": [
    { /* log 1 */ },
    { /* log 2 */ },
    { /* log 3 */ }
  ]
}

Response:

{
  "success": true,
  "inserted": 3,
  "ids": ["id1", "id2", "id3"]
}

The vij-sdk automatically batches logs to reduce network overhead.

Security Considerations

No authentication by default

VIJ Admin does not require authentication for the /api/logs endpoint by default.

Add authentication:

// middleware.ts
export function middleware(request: NextRequest) {
  const apiKey = request.headers.get('x-api-key');

  if (apiKey !== process.env.API_KEY) {
    return new NextResponse('Unauthorized', { status: 401 });
  }

  return NextResponse.next();
}

export const config = {
  matcher: '/api/logs'
};

Sanitize sensitive data

Never log sensitive information:

• Passwords
• API keys
• Credit card numbers
• Social security numbers
• Personal identification

Sanitize before sending:

const sanitizedMetadata = {
  ...metadata,
  password: undefined,
  apiKey: undefined,
  creditCard: metadata.creditCard ? 'REDACTED' : undefined
};

Validate input size

Prevent large payloads from overwhelming the server:

// In API route
const MAX_PAYLOAD_SIZE = 1024 * 100; // 100 KB

if (JSON.stringify(req.body).length > MAX_PAYLOAD_SIZE) {
  return res.status(413).json({ error: 'Payload too large' });
}

Troubleshooting

400 Bad Request

Common causes:

• Missing required fields
• Invalid severity value
• Invalid timestamp format
• Malformed JSON

Solution: Check request body matches schema exactly

413 Payload Too Large

Cause: Request body exceeds size limit

Solution:

• Reduce stack trace length
• Minimize metadata
• Use batch endpoint for multiple logs

500 Internal Server Error

Common causes:

• MongoDB connection failure
• Database write error
• Server configuration issue

Solution: Check VIJ Admin logs and MongoDB connection

CORS errors

Symptom: Browser blocks request

Solution: Ensure CORS headers allow your domain or use * for all origins

Related Endpoints

GET /api/logs

Retrieve stored error logs

GET /api/stats

Get error statistics and metrics

GET /api/groups

Retrieve error groups

SDK Reference

Use vij-sdk for automatic logging