Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion Dockerfile
Original file line number Diff line number Diff line change
Expand Up @@ -62,7 +62,7 @@ COPY --from=build --chown=nonroot:nonroot /runtime/var/lib/fanout /var/lib/fanou
USER nonroot:nonroot
WORKDIR /var/lib/fanout

EXPOSE 7520 4317 4318
EXPOSE 7520

# Startup does DuckDB catalog attachment and maintenance, so the grace period
# is generous relative to the check interval.
Expand Down
27 changes: 13 additions & 14 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -110,7 +110,7 @@ choose the installation directory.
### Docker

```sh
docker run --name fanout -p 7520:7520 -p 4317:4317 -p 4318:4318 \
docker run --name fanout -p 7520:7520 \
-v fanout-data:/var/lib/fanout/data \
-e FANOUT_AUTH_CODE_SECRET=$(openssl rand -hex 32) \
labstack/fanout:latest
Expand All @@ -122,7 +122,7 @@ your collector secrets. A standard OTLP/HTTP exporter can then use:

```sh
export OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318
export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:7520
export OTEL_EXPORTER_OTLP_HEADERS="authorization=Bearer%20$INGEST_TOKEN"
```

Expand All @@ -131,7 +131,7 @@ For a Collector on the same private container network, the forwarding side is:
```yaml
exporters:
otlp_http/fanout:
endpoint: http://fanout:4318
endpoint: http://fanout:7520
headers:
Authorization: "Bearer ${env:INGEST_TOKEN}"

Expand All @@ -146,7 +146,10 @@ This assumes the Collector's existing `otlp` receiver and an environment
variable containing the one-time token. Replace `fanout` with the private
hostname reachable from that Collector.

The equivalent OTLP/gRPC endpoint is `localhost:4317`. For later sign-in
The equivalent OTLP/gRPC endpoint is `localhost:7520` (plaintext locally).
Behind a TLS proxy, both transports use the public origin; gRPC requires
HTTP/2 to Fanout. See the [single-port migration notes](docs/operations.md#single-port-migration).
For later sign-in
without SMTP, mint a 15-minute, single-use link against the running
container's control database:

Expand All @@ -166,7 +169,7 @@ needs no such handling.
The image selects `/etc/fanout/fanout.yaml` by default. That file contains only
the container listener and data-directory defaults; it does not contain
credentials. Start a container-specific document from that file so it retains
the externally reachable HTTP and OTLP bind addresses:
the shared listener and persistent data-directory settings:

```sh
cp fanout.docker.yaml fanout.yaml
Expand All @@ -175,10 +178,8 @@ docker run -v ./fanout.yaml:/etc/fanout/fanout.yaml:ro \
labstack/fanout:latest
```

A replacement document must set `server.http_addr: ":7520"`,
`ingest.otlp_grpc_addr: ":4317"`, and `ingest.otlp_http_addr: ":4318"`;
omitting either ingest address restores its secure loopback-only built-in
default, which is unreachable through a published container port.
All surfaces use `server.addr` (`:7520` by default). Publish only that
port; OTLP/HTTP and OTLP/gRPC use the same address as the application.

### From source

Expand All @@ -201,8 +202,8 @@ Optionally set `FANOUT_AI_API_KEY` for chat and the SMTP variables shown above
for email-code login. Without SMTP, run `./bin/fanout login-link
admin@example.com` from the same configuration and data directory.

Fanout serves the UI on <http://localhost:7520>, accepts OTLP/gRPC on
`127.0.0.1:4317`, and accepts OTLP/HTTP on `127.0.0.1:4318`. The first account
Fanout serves the UI, API, MCP, OTLP/gRPC and OTLP/HTTP on
<http://localhost:7520>. The first account
created becomes the administrator and receives the ingest token once.

Point any OpenTelemetry collector or SDK at either OTLP endpoint with the
Expand Down Expand Up @@ -241,9 +242,7 @@ operators touch are:

| YAML key | Environment override | Default | Purpose |
| --- | --- | --- | --- |
| `server.http_addr` | `FANOUT_HTTP_ADDR` | `:7520` | UI, API, and MCP listener |
| `ingest.otlp_grpc_addr` | `FANOUT_OTLP_GRPC_ADDR` | `127.0.0.1:4317` | OTLP/gRPC ingest listener |
| `ingest.otlp_http_addr` | `FANOUT_OTLP_HTTP_ADDR` | `127.0.0.1:4318` | OTLP/HTTP ingest listener |
| `server.addr` | `FANOUT_ADDR` | `:7520` | UI, API, MCP, and both OTLP transports |
| `storage.data_dir` | `FANOUT_DATA_DIR` | `./data` | Parquet, query state, and control SQLite |
| `auth.mode` | `FANOUT_AUTH_MODE` | `local` | `local` (login link or SMTP) or `oidc` |
| `auth.code_secret` | `FANOUT_AUTH_CODE_SECRET` | — | Required in local mode, 32+ characters |
Expand Down
6 changes: 3 additions & 3 deletions cmd/fanout-docgen/main.go
Original file line number Diff line number Diff line change
Expand Up @@ -433,16 +433,16 @@ type groupPage struct {
var groups = map[string]groupPage{
"server": {
Title: "Server settings",
Description: "The HTTP listener, the public URL, TLS, and proxy trust.",
Summary: "Settings for the listener that serves the browser client, the API, chat and MCP.",
Description: "The shared HTTP and OTLP listener, the public URL, TLS, and proxy trust.",
Summary: "Settings for the listener that serves the browser, API, chat, MCP and both OTLP transports.",
ReadWhen: []string{
"You are putting Fanout behind a reverse proxy.",
"Browser sessions are not getting Secure cookies.",
},
},
"ingest": {
Title: "Ingest settings",
Description: "The OTLP listeners, the advertised endpoint, batching, and the default namespace.",
Description: "The advertised OTLP endpoint, batching, and the default namespace.",
Summary: "Settings for how telemetry arrives and how it is batched before it is written.",
ReadWhen: []string{
"Exporters cannot reach the instance.",
Expand Down
4 changes: 2 additions & 2 deletions cmd/fanout-docgen/routes.go
Original file line number Diff line number Diff line change
Expand Up @@ -246,8 +246,8 @@ func renderRoutes(routes []api.RouteDoc) []byte {

b.WriteString("{/* Generated by cmd/fanout-docgen from internal/api, internal/agent and cmd/fanout. Edit the generator, not this page. */}\n\n")

b.WriteString("Every route below is served on `FANOUT_HTTP_ADDR` (`:7520` by default).\n")
b.WriteString("Telemetry does not arrive here — OTLP has its own two listeners, described in\n")
b.WriteString("Every route below is served on `FANOUT_ADDR` (`:7520` by default).\n")
b.WriteString("OTLP shares this listener but uses its own handlers and ingest credential; see\n")
b.WriteString("[send your first telemetry](/start/send-telemetry).\n\n")

b.WriteString(":::note[What this table is, and what it is not]\n")
Expand Down
84 changes: 17 additions & 67 deletions cmd/fanout/main.go
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,6 @@ package main

import (
"context"
"crypto/tls"
"errors"
"flag"
"fmt"
Expand Down Expand Up @@ -39,6 +38,7 @@ import (
appmetrics "github.com/labstack/fanout/internal/metrics"
"github.com/labstack/fanout/internal/observability"
"github.com/labstack/fanout/internal/query"
"github.com/labstack/fanout/internal/server"
"github.com/labstack/fanout/internal/settings"
"github.com/labstack/fanout/internal/store"
telemetrystore "github.com/labstack/fanout/internal/telemetry/store"
Expand Down Expand Up @@ -190,53 +190,12 @@ func main() {
slog.Error("setup token init failed", "err", err)
os.Exit(1)
}
printSetupBanner(cfg.HTTPAddr, token)
printSetupBanner(cfg.Addr, token)
}

// Start gRPC ingest (OTLP)
grpcLis, err := net.Listen("tcp", cfg.OTLPGRPCAddr)
if err != nil {
slog.Error("listen gRPC failed", "err", err)
os.Exit(1)
}
grpcOpts, err := ingest.GRPCServerOptions(cfg, settingsStore)
if err != nil {
slog.Error("OTLP gRPC TLS init failed", "err", err)
os.Exit(1)
}
grpcSrv := grpc.NewServer(grpcOpts...)
grpcSrv := grpc.NewServer(ingest.GRPCServerOptions(settingsStore)...)
ing := ingest.NewServer(cfg, writer)
ingest.RegisterOTLP(grpcSrv, ing)
otlpHTTPLis, err := net.Listen("tcp", cfg.OTLPHTTPAddr)
if err != nil {
slog.Error("listen OTLP HTTP failed", "err", err)
os.Exit(1)
}
otlpHTTPSrv := &http.Server{
Handler: ingest.NewHTTPHandler(ing, settingsStore),
TLSConfig: &tls.Config{MinVersion: tls.VersionTLS13},
ReadHeaderTimeout: 5 * time.Second,
IdleTimeout: 2 * time.Minute,
}

go func() {
slog.Info("gRPC OTLP listening", "addr", cfg.OTLPGRPCAddr, "tls", cfg.TLSEnabled())
if err := grpcSrv.Serve(grpcLis); err != nil && err != grpc.ErrServerStopped {
errCh <- fmt.Errorf("gRPC server: %w", err)
}
}()
go func() {
slog.Info("HTTP OTLP listening", "addr", cfg.OTLPHTTPAddr, "tls", cfg.TLSEnabled())
var serveErr error
if cfg.TLSEnabled() {
serveErr = otlpHTTPSrv.ServeTLS(otlpHTTPLis, cfg.TLSCertFile, cfg.TLSKeyFile)
} else {
serveErr = otlpHTTPSrv.Serve(otlpHTTPLis)
}
if serveErr != nil && serveErr != http.ErrServerClosed {
errCh <- fmt.Errorf("OTLP HTTP server: %w", serveErr)
}
}()

// Start Echo HTTP API
e := echo.New()
Expand Down Expand Up @@ -417,22 +376,14 @@ func main() {
e.GET("/", spa)
e.GET("/*", spa)

// Run HTTP
httpCtx, httpCancel := context.WithCancel(context.Background())
httpSrv := server.New(cfg.Addr, e, ingest.NewHTTPHandler(ing, settingsStore), grpcSrv)
go func() {
sc := echo.StartConfig{
Address: cfg.HTTPAddr,
HideBanner: true,
GracefulTimeout: 5 * time.Second,
}
slog.Info("HTTP listening", "addr", cfg.HTTPAddr, "tls", cfg.TLSEnabled())
slog.Info("HTTP and OTLP listening", "addr", cfg.Addr, "tls", cfg.TLSEnabled())
var err error
if cfg.TLSEnabled() {
// Match the OTLP gRPC listener's TLS 1.3 floor; Echo otherwise defaults to 1.2.
sc.TLSConfig = &tls.Config{MinVersion: tls.VersionTLS13}
err = sc.StartTLS(httpCtx, e, cfg.TLSCertFile, cfg.TLSKeyFile)
err = httpSrv.ListenAndServeTLS(cfg.TLSCertFile, cfg.TLSKeyFile)
} else {
err = sc.Start(httpCtx, e)
err = httpSrv.ListenAndServe()
}
if err != nil && err != http.ErrServerClosed {
errCh <- fmt.Errorf("HTTP server: %w", err)
Expand All @@ -450,22 +401,21 @@ func main() {
slog.Error("fatal error, shutting down", "err", err)
}

// Stop accepting OTLP and let in-flight exporters finish while the writer is
// still draining. Cancelling the writer first could strand a handler on a full
// channel or accept rows after its final drain.
otlpShutdownCtx, otlpShutdownCancel := context.WithTimeout(context.Background(), 5*time.Second)
if err := otlpHTTPSrv.Shutdown(otlpShutdownCtx); err != nil {
slog.Error("OTLP HTTP graceful shutdown failed", "err", err)
_ = otlpHTTPSrv.Close()
// Stop every surface and finish in-flight exports before stopping the writer.
// The deadline also bounds long-lived SSE requests; Close cancels any that
// remain. net/http owns the gRPC connections, including plaintext HTTP/2.
shutdownCtx, shutdownCancel := context.WithTimeout(context.Background(), 5*time.Second)
if err := httpSrv.Shutdown(shutdownCtx); err != nil {
slog.Error("HTTP graceful shutdown failed", "err", err)
_ = httpSrv.Close()
}
otlpShutdownCancel()
grpcSrv.GracefulStop()
shutdownCancel()
grpcSrv.Stop()
cancel()
writer.Wait()
if err := <-writerResult; err != nil {
slog.Error("telemetry writer stopped with unwritten telemetry", "err", err)
}
httpCancel() // triggers graceful HTTP shutdown (5s timeout)
}

func parseCommandLine(args []string, output io.Writer) (configPath string, showVersion bool, loginEmail, healthURL string, repair *repairCommand, err error) {
Expand Down Expand Up @@ -630,7 +580,7 @@ func browserLoginURL(cfg config.Config) *url.URL {
publicURL.Fragment = ""
return publicURL
}
loginURL, _ := url.Parse(setupLoginURL(cfg.HTTPAddr))
loginURL, _ := url.Parse(setupLoginURL(cfg.Addr))
return loginURL
}

Expand Down
2 changes: 1 addition & 1 deletion cmd/fanout/main_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -157,7 +157,7 @@ func TestCreateLoginLink(t *testing.T) {
AuthMode: "local",
AuthCodeSecret: "0123456789abcdef0123456789abcdef",
DataDir: t.TempDir(),
HTTPAddr: ":7520",
Addr: ":7520",
PublicURL: "https://fanout.example.com/base",
}
if err := os.MkdirAll(cfg.ControlDir(), 0o755); err != nil {
Expand Down
Loading
Loading