Any stack, no SDK
Vigie has no SDK of its own to install. It reads standard OpenTelemetry over OTLP/HTTP, so anything that can export OTLP can send to it: the official SDKs in Node, Python, Go, Java, .NET, Ruby or PHP, an OpenTelemetry Collector, or a curl.
Where to send
| Endpoint | When |
|---|---|
<VIGIE_URL>/otlp | One URL for everything, behind HTTPS. Set it as OTEL_EXPORTER_OTLP_ENDPOINT. |
http://localhost:4318 | The ingest port, on your machine. |
On a server, add the ingest key from Settings, Tokens: OTEL_EXPORTER_OTLP_HEADERS="authorization=Bearer vk_…".
Traces and metrics need nothing else. Logs become useful once they carry a few agreed names.
The wide-event contract
A wide event is one log record per unit of work. Vigie reads its attributes, dotted or nested:
| Attribute | Makes it | Example |
|---|---|---|
method | a request | POST |
path | the URL path as called | /orders/o_81/checkout |
route.pattern | the route as written in code, to group requests | /orders/:id/checkout |
status | the response status | 201 |
durationMs | how long it took | 42 |
outcome | succeeded, failed, denied or skipped | failed |
reason | a short code for why it failed | CART_EMPTY |
why, fix | one sentence each, shown on the issue | The cart has no items. |
user.id | who did it | u_12 |
task.kind | a task attempt | emails.send |
task.id, task.attempt | which run, which try | job-81, 2 |
task.queue, task.waitMs | where it waited, and how long | emails, 120 |
task.integration | the provider it talks to | postwing |
taskOutcome.type, taskOutcome.code | SUCCEEDED, FAILED, SKIPPED or RETRY, and why | SKIPPED, UNSUBSCRIBED |
operation | any other unit of work: a cron, a script | reports.nightly |
error.name, error.message, error.stack | the error behind a failure |
Put the record's trace id in the log record itself, as every OpenTelemetry SDK does, and the event opens on its trace.
Two gauges feed the task backlog: vigie.tasks.backlog with a task.state attribute (due, scheduled, running, held) and vigie.tasks.oldest_due_age in seconds. If your app already sends them under another prefix, set VIGIE_TASK_METRICS to it.
Try it with curl
curl -X POST http://localhost:4318/v1/logs -H 'content-type: application/json' -d '{
"resourceLogs": [{
"resource": { "attributes": [{ "key": "service.name", "value": { "stringValue": "shop-api" } }] },
"scopeLogs": [{ "logRecords": [{
"timeUnixNano": "'$(date +%s)000000000'",
"body": { "stringValue": "POST /orders 201" },
"attributes": [
{ "key": "method", "value": { "stringValue": "POST" } },
{ "key": "route.pattern", "value": { "stringValue": "/orders" } },
{ "key": "status", "value": { "intValue": "201" } },
{ "key": "durationMs", "value": { "doubleValue": 42 } },
{ "key": "outcome", "value": { "stringValue": "succeeded" } }
]
}]}]
}]
}'
Open Logs: it is there as a request, POST /orders 201 in 42 ms.
Node, with the OpenTelemetry SDK
import { logs } from '@opentelemetry/api-logs'
const logger = logs.getLogger('http')
app.use((req, res, next) => {
const started = performance.now()
res.on('finish', () => {
logger.emit({
body: `${req.method} ${req.path} ${res.statusCode}`,
attributes: {
method: req.method,
path: req.path,
'route.pattern': req.route?.path,
status: res.statusCode,
durationMs: Math.round(performance.now() - started),
outcome: res.statusCode >= 400 ? 'failed' : 'succeeded',
},
})
})
next()
})
Python
import logging, time
from opentelemetry.sdk._logs import LoggerProvider, LoggingHandler
from opentelemetry.sdk._logs.export import BatchLogRecordProcessor
from opentelemetry.exporter.otlp.proto.http._log_exporter import OTLPLogExporter
provider = LoggerProvider()
provider.add_log_record_processor(BatchLogRecordProcessor(OTLPLogExporter()))
log = logging.getLogger("http")
log.addHandler(LoggingHandler(logger_provider=provider))
@app.middleware("http")
async def wide_event(request, call_next):
started = time.perf_counter()
response = await call_next(request)
log.info(f"{request.method} {request.url.path} {response.status_code}", extra={
"method": request.method,
"path": request.url.path,
"status": response.status_code,
"durationMs": round((time.perf_counter() - started) * 1000),
"outcome": "failed" if response.status_code >= 400 else "succeeded",
})
return response
Go
type statusRecorder struct {
http.ResponseWriter
status int
}
func (r *statusRecorder) WriteHeader(code int) { r.status = code; r.ResponseWriter.WriteHeader(code) }
var logger = global.GetLoggerProvider().Logger("http")
// drop-in: wrap your mux with wideEvent(mux)
func wideEvent(next http.Handler) http.Handler {
return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
started := time.Now()
rec := &statusRecorder{ResponseWriter: w, status: 200}
next.ServeHTTP(rec, r)
var record log.Record
record.SetBody(log.StringValue(fmt.Sprintf("%s %s %d", r.Method, r.URL.Path, rec.status)))
record.AddAttributes(
log.String("method", r.Method),
log.String("path", r.URL.Path),
log.Int("status", rec.status),
log.Int64("durationMs", time.Since(started).Milliseconds()),
)
logger.Emit(r.Context(), record)
})
}
Every snippet reads the endpoint from OTEL_EXPORTER_OTLP_ENDPOINT, as the SDKs do.
<VIGIE_URL>/otlp with recordShape: 'compact'. The Adonis and NestJS packages use it underneath.