Merge pull request #165 from prometheus-community/better-rest-docs

Clarify documentation

Author: Nexucis

cmd/promql-langserver/promql-langserver.go

@@ -23,7 +23,6 @@ import (
 
 	kitlog "github.com/go-kit/kit/log"
 	promClient "github.com/prometheus-community/promql-langserver/prometheus"
-	"github.com/prometheus/client_golang/prometheus"
 
 	"github.com/prometheus-community/promql-langserver/langserver"
 	"github.com/prometheus-community/promql-langserver/rest"
@@ -59,7 +58,7 @@ func main() {
 
 		logger = kitlog.NewSyncLogger(logger)
 
-		handler, err := rest.CreateInstHandler(context.Background(), prometheusClient, prometheus.NewRegistry(), logger)
+		handler, err := rest.CreateInstHandler(context.Background(), prometheusClient, logger)
 		if err != nil {
 			log.Fatal(err)
 		}

rest/handler.go

@@ -33,36 +33,51 @@ import (
 
 // CreateHandler creates an http.Handler for the PromQL langserver REST API.
 //
-// Expects a prometheus Client as a second argument.
+// If metadata is fetched from a remote Prometheus, the metadataService
+// implementation from the promql-langserver/prometheus package can be used,
+// otherwise you need to provide your own implementation of the interface.
+//
 // The provided Logger should be synchronized.
 func CreateHandler(ctx context.Context, metadataService promClient.MetadataService, logger log.Logger) (http.Handler, error) {
-	return CreateInstHandler(ctx, metadataService, nil, logger)
+	return createHandler(ctx, metadataService, logger, false)
 }
 
 // CreateInstHandler creates an instrumented http.Handler for the PromQL langserver REST API.
+// In addition to the endpoints created with CreateHandler, a /metrics endpoint // is provided.
+//
+// If you use the REST API with some middleware that already provides its own
+// instrumentation, use CreateHandler instead.
+//
+// If metadata is fetched from a remote Prometheus, the metadataService
+// implementation from the promql-langserver/prometheus package can be used,
+// otherwise you need to provide your own implementation of the interface.
 //
-// Expects a prometheus Client as a second argument and a Registry as third argument.
 // The provided Logger should be synchronized.
-func CreateInstHandler(ctx context.Context, metadataService promClient.MetadataService, r *prometheus.Registry, logger log.Logger) (http.Handler, error) {
+func CreateInstHandler(ctx context.Context, metadataService promClient.MetadataService, logger log.Logger) (http.Handler, error) {
+	return createHandler(ctx, metadataService, logger, true)
+}
+func createHandler(ctx context.Context, metadataService promClient.MetadataService, logger log.Logger, metricsEnpoint bool) (http.Handler, error) {
 	lgs, err := langserver.CreateHeadlessServer(ctx, metadataService, logger)
 	if err != nil {
 		return nil, err
 	}
 
 	ls := &langserverHandler{langserver: lgs}
 	ls.m = make(map[string]http.Handler)
-	ls.createHandlers(r)
+	ls.createHandlers(metricsEnpoint)
 
 	return ls, nil
 }
 
-func (h *langserverHandler) createHandlers(r *prometheus.Registry) {
+func (h *langserverHandler) createHandlers(metricsEndpoint bool) {
 	diagnostics := newSubHandler(h, diagnosticsHandler)
 	completion := newSubHandler(h, completionHandler)
 	hover := newSubHandler(h, hoverHandler)
 	signatureHelp := newSubHandler(h, signatureHelpHandler)
 
-	if r != nil {
+	if metricsEndpoint {
+		r := prometheus.NewRegistry()
+
 		httpRequestsTotal := prometheus.NewCounterVec(prometheus.CounterOpts{
 			Name: "http_requests_total",
 			Help: "Count of all HTTP requests",