pulse quickstart

0. Install and import

go get github.com/vagnercazarotto/pulse

import "github.com/vagnercazarotto/pulse"

1. Recommended default config

CollectInterval: 10 * time.Second
ExportInterval:  10 * time.Second
ExportTimeout:   3 * time.Second
BufferSize:      10_000
ExportMaxRetries: 5
BackoffInitial:  500 * time.Millisecond
BackoffMax:      30 * time.Second
BackoffJitter:   0.20
ShutdownTimeout: 5 * time.Second

2. Agent lifecycle

• Start initializes collectors and exporters.
• Stop is idempotent.
• Start after Stop on the same instance returns ErrAgentStopped.

3. Metrics with labels

errors := agent.Metrics().Counter("modbus.errors", map[string]string{
  "device": "boiler-01",
  "protocol": "tcp",
})
errors.Inc()

latency, err := agent.Metrics().Histogram(
  "modbus.poll_latency_s",
  map[string]string{"device": "boiler-01"},
  0.01, 0.05, 0.1, 0.5, 1.0,
)

4. Export and resilience

• Exporter receives context for timeout/cancellation.
• Retry uses exponential backoff with jitter, up to 5 attempts.
• When the buffer is full, oldest-evict is applied and overflow_count is incremented.

5. End-to-end example

httpExporter := pulse.NewHTTPExporter(pulse.HTTPExporterConfig{
  Addr: "127.0.0.1:9090",
})

agent := pulse.New(pulse.Config{
  Exporters: []pulse.Exporter{httpExporter},
  WAL: &pulse.WALConfig{Dir: "./pulse-wal"},
})

requests := agent.Metrics().Counter("app.requests_total", map[string]string{
  "service": "gateway",
})

if err := agent.Start(); err != nil {
  log.Fatal(err)
}
defer agent.Stop()

requests.Inc()