SagerNet / SagerNet/sing-box

[Question] Plan to enhance observability?

Open
#1,564 3 comments 11 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

enhancement
Dominant language
Go
Stars
38.2k
Forks
4.6k
Avg merge
19d 15h
Merged PRs (30d)
1

Description

Hi Sekai and sing-box developers,

Thanks for making such a great tool. I've used sing-box for my home lab for several weeks. Complete integrations and the rigorous implementation really makes sing-box stand out from the crowd.

I'm curious that, do we have any plans for improving the observability of sing-box? Not only the clash dashboard compatibility, but also, for example, metrics, tracing, structured/JSON logs.

Here are some mature solution for golang, like Prometheus for metrics: https://github.com/prometheus/client_golang, and OpenTelemetry for tracing: https://opentelemetry.io/docs/languages/go/getting-started/.

I have to say that it could be a bit over kill to require "observability" for an app running on end-user's phones, laptops. But for people like me who run sing-box on a headless server, tracing and metrics can help a lot when address a network issue.

I used to built my own gateway based on Ubuntu, V2Ray, tproxy, ipset, iptables, and dnsmasq. I even made it unattended deployment with Ansible. However, eventually I gave up because of the over complexity and lack of observability. None of these has been made for "the" use case. Every time user complained "I can't open Google", connection reset by remote, I hardly cannot find the root cause in this ipset->dnsmasq->iptables->v2ray traffic chain. For me it is nightmare trying to identify where the connections go and why it didn't work.

Actually, I tried to build a Prometheus exporter to collect the stats from V2Ray API and exposes to Prometheus: https://github.com/wi1dcard/v2ray-exporter. But it was still not enough.

Anyway, long story short, if you'd like to enhance the observability, it would be very nice. Here is what I expected:

  1. JSON log
  2. More info in the log (for example print downloaded/uploaded bytes when a connection is closed, this is available in clash dashboard)
  3. Tracing (I saw there are pprof integration already, so this might not be that important?)
  4. Metrics (such as inbound/outbound bandwidth, number of connections, etc)

Please let me know your thoughts. Perhaps I can do some if it's on the plan.

Contributor guide

No contributing guide indexed for this repository

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

The issue does not name repository files or tests. Start by reviewing the existing pprof integration and the current logging and monitoring approach, then clarify which of JSON logs, richer connection details, tracing, and metrics are in scope. Done requires an agreed scope and implementation plan for the selected observability work.

Written by the indexing model from the issue text.

Assessment

Tech stack
go, prometheus
Domain
observability-sre
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Needs clarification
Newbie friendliness
20/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.