1// Copyright 2016 The Prometheus Authors 2// Licensed under the Apache License, Version 2.0 (the "License"); 3// you may not use this file except in compliance with the License. 4// You may obtain a copy of the License at 5// 6// http://www.apache.org/licenses/LICENSE-2.0 7// 8// Unless required by applicable law or agreed to in writing, software 9// distributed under the License is distributed on an "AS IS" BASIS, 10// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 11// See the License for the specific language governing permissions and 12// limitations under the License. 13 14// Copyright (c) 2013, The Prometheus Authors 15// All rights reserved. 16// 17// Use of this source code is governed by a BSD-style license that can be found 18// in the LICENSE file. 19 20// Package promhttp contains functions to create http.Handler instances to 21// expose Prometheus metrics via HTTP. In later versions of this package, it 22// will also contain tooling to instrument instances of http.Handler and 23// http.RoundTripper. 24// 25// promhttp.Handler acts on the prometheus.DefaultGatherer. With HandlerFor, 26// you can create a handler for a custom registry or anything that implements 27// the Gatherer interface. It also allows to create handlers that act 28// differently on errors or allow to log errors. 29package promhttp 30 31import ( 32 "bytes" 33 "compress/gzip" 34 "fmt" 35 "io" 36 "net/http" 37 "strings" 38 "sync" 39 40 "github.com/prometheus/common/expfmt" 41 42 "github.com/prometheus/client_golang/prometheus" 43) 44 45const ( 46 contentTypeHeader = "Content-Type" 47 contentLengthHeader = "Content-Length" 48 contentEncodingHeader = "Content-Encoding" 49 acceptEncodingHeader = "Accept-Encoding" 50) 51 52var bufPool sync.Pool 53 54func getBuf() *bytes.Buffer { 55 buf := bufPool.Get() 56 if buf == nil { 57 return &bytes.Buffer{} 58 } 59 return buf.(*bytes.Buffer) 60} 61 62func giveBuf(buf *bytes.Buffer) { 63 buf.Reset() 64 bufPool.Put(buf) 65} 66 67// Handler returns an HTTP handler for the prometheus.DefaultGatherer. The 68// Handler uses the default HandlerOpts, i.e. report the first error as an HTTP 69// error, no error logging, and compression if requested by the client. 70// 71// If you want to create a Handler for the DefaultGatherer with different 72// HandlerOpts, create it with HandlerFor with prometheus.DefaultGatherer and 73// your desired HandlerOpts. 74func Handler() http.Handler { 75 return HandlerFor(prometheus.DefaultGatherer, HandlerOpts{}) 76} 77 78// HandlerFor returns an http.Handler for the provided Gatherer. The behavior 79// of the Handler is defined by the provided HandlerOpts. 80func HandlerFor(reg prometheus.Gatherer, opts HandlerOpts) http.Handler { 81 return http.HandlerFunc(func(w http.ResponseWriter, req *http.Request) { 82 mfs, err := reg.Gather() 83 if err != nil { 84 if opts.ErrorLog != nil { 85 opts.ErrorLog.Println("error gathering metrics:", err) 86 } 87 switch opts.ErrorHandling { 88 case PanicOnError: 89 panic(err) 90 case ContinueOnError: 91 if len(mfs) == 0 { 92 http.Error(w, "No metrics gathered, last error:\n\n"+err.Error(), http.StatusInternalServerError) 93 return 94 } 95 case HTTPErrorOnError: 96 http.Error(w, "An error has occurred during metrics gathering:\n\n"+err.Error(), http.StatusInternalServerError) 97 return 98 } 99 } 100 101 contentType := expfmt.Negotiate(req.Header) 102 buf := getBuf() 103 defer giveBuf(buf) 104 writer, encoding := decorateWriter(req, buf, opts.DisableCompression) 105 enc := expfmt.NewEncoder(writer, contentType) 106 var lastErr error 107 for _, mf := range mfs { 108 if err := enc.Encode(mf); err != nil { 109 lastErr = err 110 if opts.ErrorLog != nil { 111 opts.ErrorLog.Println("error encoding metric family:", err) 112 } 113 switch opts.ErrorHandling { 114 case PanicOnError: 115 panic(err) 116 case ContinueOnError: 117 // Handled later. 118 case HTTPErrorOnError: 119 http.Error(w, "An error has occurred during metrics encoding:\n\n"+err.Error(), http.StatusInternalServerError) 120 return 121 } 122 } 123 } 124 if closer, ok := writer.(io.Closer); ok { 125 closer.Close() 126 } 127 if lastErr != nil && buf.Len() == 0 { 128 http.Error(w, "No metrics encoded, last error:\n\n"+err.Error(), http.StatusInternalServerError) 129 return 130 } 131 header := w.Header() 132 header.Set(contentTypeHeader, string(contentType)) 133 header.Set(contentLengthHeader, fmt.Sprint(buf.Len())) 134 if encoding != "" { 135 header.Set(contentEncodingHeader, encoding) 136 } 137 w.Write(buf.Bytes()) 138 // TODO(beorn7): Consider streaming serving of metrics. 139 }) 140} 141 142// HandlerErrorHandling defines how a Handler serving metrics will handle 143// errors. 144type HandlerErrorHandling int 145 146// These constants cause handlers serving metrics to behave as described if 147// errors are encountered. 148const ( 149 // Serve an HTTP status code 500 upon the first error 150 // encountered. Report the error message in the body. 151 HTTPErrorOnError HandlerErrorHandling = iota 152 // Ignore errors and try to serve as many metrics as possible. However, 153 // if no metrics can be served, serve an HTTP status code 500 and the 154 // last error message in the body. Only use this in deliberate "best 155 // effort" metrics collection scenarios. It is recommended to at least 156 // log errors (by providing an ErrorLog in HandlerOpts) to not mask 157 // errors completely. 158 ContinueOnError 159 // Panic upon the first error encountered (useful for "crash only" apps). 160 PanicOnError 161) 162 163// Logger is the minimal interface HandlerOpts needs for logging. Note that 164// log.Logger from the standard library implements this interface, and it is 165// easy to implement by custom loggers, if they don't do so already anyway. 166type Logger interface { 167 Println(v ...interface{}) 168} 169 170// HandlerOpts specifies options how to serve metrics via an http.Handler. The 171// zero value of HandlerOpts is a reasonable default. 172type HandlerOpts struct { 173 // ErrorLog specifies an optional logger for errors collecting and 174 // serving metrics. If nil, errors are not logged at all. 175 ErrorLog Logger 176 // ErrorHandling defines how errors are handled. Note that errors are 177 // logged regardless of the configured ErrorHandling provided ErrorLog 178 // is not nil. 179 ErrorHandling HandlerErrorHandling 180 // If DisableCompression is true, the handler will never compress the 181 // response, even if requested by the client. 182 DisableCompression bool 183} 184 185// decorateWriter wraps a writer to handle gzip compression if requested. It 186// returns the decorated writer and the appropriate "Content-Encoding" header 187// (which is empty if no compression is enabled). 188func decorateWriter(request *http.Request, writer io.Writer, compressionDisabled bool) (io.Writer, string) { 189 if compressionDisabled { 190 return writer, "" 191 } 192 header := request.Header.Get(acceptEncodingHeader) 193 parts := strings.Split(header, ",") 194 for _, part := range parts { 195 part := strings.TrimSpace(part) 196 if part == "gzip" || strings.HasPrefix(part, "gzip;") { 197 return gzip.NewWriter(writer), "gzip" 198 } 199 } 200 return writer, "" 201} 202