stats.go

Documentation: go.opencensus.io/plugin/ochttp

     1  // Copyright 2018, OpenCensus Authors
     2  //
     3  // Licensed under the Apache License, Version 2.0 (the "License");
     4  // you may not use this file except in compliance with the License.
     5  // You may obtain a copy of the License at
     6  //
     7  //     http://www.apache.org/licenses/LICENSE-2.0
     8  //
     9  // Unless required by applicable law or agreed to in writing, software
    10  // distributed under the License is distributed on an "AS IS" BASIS,
    11  // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    12  // See the License for the specific language governing permissions and
    13  // limitations under the License.
    14  
    15  package ochttp
    16  
    17  import (
    18  	"go.opencensus.io/stats"
    19  	"go.opencensus.io/stats/view"
    20  	"go.opencensus.io/tag"
    21  )
    22  
    23  // Deprecated: client HTTP measures.
    24  var (
    25  	// Deprecated: Use a Count aggregation over one of the other client measures to achieve the same effect.
    26  	ClientRequestCount = stats.Int64(
    27  		"opencensus.io/http/client/request_count",
    28  		"Number of HTTP requests started",
    29  		stats.UnitDimensionless)
    30  	// Deprecated: Use ClientSentBytes.
    31  	ClientRequestBytes = stats.Int64(
    32  		"opencensus.io/http/client/request_bytes",
    33  		"HTTP request body size if set as ContentLength (uncompressed)",
    34  		stats.UnitBytes)
    35  	// Deprecated: Use ClientReceivedBytes.
    36  	ClientResponseBytes = stats.Int64(
    37  		"opencensus.io/http/client/response_bytes",
    38  		"HTTP response body size (uncompressed)",
    39  		stats.UnitBytes)
    40  	// Deprecated: Use ClientRoundtripLatency.
    41  	ClientLatency = stats.Float64(
    42  		"opencensus.io/http/client/latency",
    43  		"End-to-end latency",
    44  		stats.UnitMilliseconds)
    45  )
    46  
    47  // The following client HTTP measures are supported for use in custom views.
    48  var (
    49  	ClientSentBytes = stats.Int64(
    50  		"opencensus.io/http/client/sent_bytes",
    51  		"Total bytes sent in request body (not including headers)",
    52  		stats.UnitBytes,
    53  	)
    54  	ClientReceivedBytes = stats.Int64(
    55  		"opencensus.io/http/client/received_bytes",
    56  		"Total bytes received in response bodies (not including headers but including error responses with bodies)",
    57  		stats.UnitBytes,
    58  	)
    59  	ClientRoundtripLatency = stats.Float64(
    60  		"opencensus.io/http/client/roundtrip_latency",
    61  		"Time between first byte of request headers sent to last byte of response received, or terminal error",
    62  		stats.UnitMilliseconds,
    63  	)
    64  )
    65  
    66  // The following server HTTP measures are supported for use in custom views:
    67  var (
    68  	ServerRequestCount = stats.Int64(
    69  		"opencensus.io/http/server/request_count",
    70  		"Number of HTTP requests started",
    71  		stats.UnitDimensionless)
    72  	ServerRequestBytes = stats.Int64(
    73  		"opencensus.io/http/server/request_bytes",
    74  		"HTTP request body size if set as ContentLength (uncompressed)",
    75  		stats.UnitBytes)
    76  	ServerResponseBytes = stats.Int64(
    77  		"opencensus.io/http/server/response_bytes",
    78  		"HTTP response body size (uncompressed)",
    79  		stats.UnitBytes)
    80  	ServerLatency = stats.Float64(
    81  		"opencensus.io/http/server/latency",
    82  		"End-to-end latency",
    83  		stats.UnitMilliseconds)
    84  )
    85  
    86  // The following tags are applied to stats recorded by this package. Host, Path
    87  // and Method are applied to all measures. StatusCode is not applied to
    88  // ClientRequestCount or ServerRequestCount, since it is recorded before the status is known.
    89  var (
    90  	// Host is the value of the HTTP Host header.
    91  	//
    92  	// The value of this tag can be controlled by the HTTP client, so you need
    93  	// to watch out for potentially generating high-cardinality labels in your
    94  	// metrics backend if you use this tag in views.
    95  	Host = tag.MustNewKey("http.host")
    96  
    97  	// StatusCode is the numeric HTTP response status code,
    98  	// or "error" if a transport error occurred and no status code was read.
    99  	StatusCode = tag.MustNewKey("http.status")
   100  
   101  	// Path is the URL path (not including query string) in the request.
   102  	//
   103  	// The value of this tag can be controlled by the HTTP client, so you need
   104  	// to watch out for potentially generating high-cardinality labels in your
   105  	// metrics backend if you use this tag in views.
   106  	Path = tag.MustNewKey("http.path")
   107  
   108  	// Method is the HTTP method of the request, capitalized (GET, POST, etc.).
   109  	Method = tag.MustNewKey("http.method")
   110  
   111  	// KeyServerRoute is a low cardinality string representing the logical
   112  	// handler of the request. This is usually the pattern registered on the a
   113  	// ServeMux (or similar string).
   114  	KeyServerRoute = tag.MustNewKey("http_server_route")
   115  )
   116  
   117  // Client tag keys.
   118  var (
   119  	// KeyClientMethod is the HTTP method, capitalized (i.e. GET, POST, PUT, DELETE, etc.).
   120  	KeyClientMethod = tag.MustNewKey("http_client_method")
   121  	// KeyClientPath is the URL path (not including query string).
   122  	KeyClientPath = tag.MustNewKey("http_client_path")
   123  	// KeyClientStatus is the HTTP status code as an integer (e.g. 200, 404, 500.), or "error" if no response status line was received.
   124  	KeyClientStatus = tag.MustNewKey("http_client_status")
   125  	// KeyClientHost is the value of the request Host header.
   126  	KeyClientHost = tag.MustNewKey("http_client_host")
   127  )
   128  
   129  // Default distributions used by views in this package.
   130  var (
   131  	DefaultSizeDistribution    = view.Distribution(1024, 2048, 4096, 16384, 65536, 262144, 1048576, 4194304, 16777216, 67108864, 268435456, 1073741824, 4294967296)
   132  	DefaultLatencyDistribution = view.Distribution(1, 2, 3, 4, 5, 6, 8, 10, 13, 16, 20, 25, 30, 40, 50, 65, 80, 100, 130, 160, 200, 250, 300, 400, 500, 650, 800, 1000, 2000, 5000, 10000, 20000, 50000, 100000)
   133  )
   134  
   135  // Package ochttp provides some convenience views for client measures.
   136  // You still need to register these views for data to actually be collected.
   137  var (
   138  	ClientSentBytesDistribution = &view.View{
   139  		Name:        "opencensus.io/http/client/sent_bytes",
   140  		Measure:     ClientSentBytes,
   141  		Aggregation: DefaultSizeDistribution,
   142  		Description: "Total bytes sent in request body (not including headers), by HTTP method and response status",
   143  		TagKeys:     []tag.Key{KeyClientMethod, KeyClientStatus},
   144  	}
   145  
   146  	ClientReceivedBytesDistribution = &view.View{
   147  		Name:        "opencensus.io/http/client/received_bytes",
   148  		Measure:     ClientReceivedBytes,
   149  		Aggregation: DefaultSizeDistribution,
   150  		Description: "Total bytes received in response bodies (not including headers but including error responses with bodies), by HTTP method and response status",
   151  		TagKeys:     []tag.Key{KeyClientMethod, KeyClientStatus},
   152  	}
   153  
   154  	ClientRoundtripLatencyDistribution = &view.View{
   155  		Name:        "opencensus.io/http/client/roundtrip_latency",
   156  		Measure:     ClientRoundtripLatency,
   157  		Aggregation: DefaultLatencyDistribution,
   158  		Description: "End-to-end latency, by HTTP method and response status",
   159  		TagKeys:     []tag.Key{KeyClientMethod, KeyClientStatus},
   160  	}
   161  
   162  	ClientCompletedCount = &view.View{
   163  		Name:        "opencensus.io/http/client/completed_count",
   164  		Measure:     ClientRoundtripLatency,
   165  		Aggregation: view.Count(),
   166  		Description: "Count of completed requests, by HTTP method and response status",
   167  		TagKeys:     []tag.Key{KeyClientMethod, KeyClientStatus},
   168  	}
   169  )
   170  
   171  // Deprecated: Old client Views.
   172  var (
   173  	// Deprecated: No direct replacement, but see ClientCompletedCount.
   174  	ClientRequestCountView = &view.View{
   175  		Name:        "opencensus.io/http/client/request_count",
   176  		Description: "Count of HTTP requests started",
   177  		Measure:     ClientRequestCount,
   178  		Aggregation: view.Count(),
   179  	}
   180  
   181  	// Deprecated: Use ClientSentBytesDistribution.
   182  	ClientRequestBytesView = &view.View{
   183  		Name:        "opencensus.io/http/client/request_bytes",
   184  		Description: "Size distribution of HTTP request body",
   185  		Measure:     ClientSentBytes,
   186  		Aggregation: DefaultSizeDistribution,
   187  	}
   188  
   189  	// Deprecated: Use ClientReceivedBytesDistribution instead.
   190  	ClientResponseBytesView = &view.View{
   191  		Name:        "opencensus.io/http/client/response_bytes",
   192  		Description: "Size distribution of HTTP response body",
   193  		Measure:     ClientReceivedBytes,
   194  		Aggregation: DefaultSizeDistribution,
   195  	}
   196  
   197  	// Deprecated: Use ClientRoundtripLatencyDistribution instead.
   198  	ClientLatencyView = &view.View{
   199  		Name:        "opencensus.io/http/client/latency",
   200  		Description: "Latency distribution of HTTP requests",
   201  		Measure:     ClientRoundtripLatency,
   202  		Aggregation: DefaultLatencyDistribution,
   203  	}
   204  
   205  	// Deprecated: Use ClientCompletedCount instead.
   206  	ClientRequestCountByMethod = &view.View{
   207  		Name:        "opencensus.io/http/client/request_count_by_method",
   208  		Description: "Client request count by HTTP method",
   209  		TagKeys:     []tag.Key{Method},
   210  		Measure:     ClientSentBytes,
   211  		Aggregation: view.Count(),
   212  	}
   213  
   214  	// Deprecated: Use ClientCompletedCount instead.
   215  	ClientResponseCountByStatusCode = &view.View{
   216  		Name:        "opencensus.io/http/client/response_count_by_status_code",
   217  		Description: "Client response count by status code",
   218  		TagKeys:     []tag.Key{StatusCode},
   219  		Measure:     ClientRoundtripLatency,
   220  		Aggregation: view.Count(),
   221  	}
   222  )
   223  
   224  // Package ochttp provides some convenience views for server measures.
   225  // You still need to register these views for data to actually be collected.
   226  var (
   227  	ServerRequestCountView = &view.View{
   228  		Name:        "opencensus.io/http/server/request_count",
   229  		Description: "Count of HTTP requests started",
   230  		Measure:     ServerRequestCount,
   231  		Aggregation: view.Count(),
   232  	}
   233  
   234  	ServerRequestBytesView = &view.View{
   235  		Name:        "opencensus.io/http/server/request_bytes",
   236  		Description: "Size distribution of HTTP request body",
   237  		Measure:     ServerRequestBytes,
   238  		Aggregation: DefaultSizeDistribution,
   239  	}
   240  
   241  	ServerResponseBytesView = &view.View{
   242  		Name:        "opencensus.io/http/server/response_bytes",
   243  		Description: "Size distribution of HTTP response body",
   244  		Measure:     ServerResponseBytes,
   245  		Aggregation: DefaultSizeDistribution,
   246  	}
   247  
   248  	ServerLatencyView = &view.View{
   249  		Name:        "opencensus.io/http/server/latency",
   250  		Description: "Latency distribution of HTTP requests",
   251  		Measure:     ServerLatency,
   252  		Aggregation: DefaultLatencyDistribution,
   253  	}
   254  
   255  	ServerRequestCountByMethod = &view.View{
   256  		Name:        "opencensus.io/http/server/request_count_by_method",
   257  		Description: "Server request count by HTTP method",
   258  		TagKeys:     []tag.Key{Method},
   259  		Measure:     ServerRequestCount,
   260  		Aggregation: view.Count(),
   261  	}
   262  
   263  	ServerResponseCountByStatusCode = &view.View{
   264  		Name:        "opencensus.io/http/server/response_count_by_status_code",
   265  		Description: "Server response count by status code",
   266  		TagKeys:     []tag.Key{StatusCode},
   267  		Measure:     ServerLatency,
   268  		Aggregation: view.Count(),
   269  	}
   270  )
   271  
   272  // DefaultClientViews are the default client views provided by this package.
   273  // Deprecated: No replacement. Register the views you would like individually.
   274  var DefaultClientViews = []*view.View{
   275  	ClientRequestCountView,
   276  	ClientRequestBytesView,
   277  	ClientResponseBytesView,
   278  	ClientLatencyView,
   279  	ClientRequestCountByMethod,
   280  	ClientResponseCountByStatusCode,
   281  }
   282  
   283  // DefaultServerViews are the default server views provided by this package.
   284  // Deprecated: No replacement. Register the views you would like individually.
   285  var DefaultServerViews = []*view.View{
   286  	ServerRequestCountView,
   287  	ServerRequestBytesView,
   288  	ServerResponseBytesView,
   289  	ServerLatencyView,
   290  	ServerRequestCountByMethod,
   291  	ServerResponseCountByStatusCode,
   292  }
   293
View as plain text