planetscale 0.3.1 → 0.3.3

data/vendor/go.uber.org/zap/FAQ.md

@@ -1,164 +0,0 @@
-# Frequently Asked Questions
-
-## Design
-
-### Why spend so much effort on logger performance?
-
-Of course, most applications won't notice the impact of a slow logger: they
-already take tens or hundreds of milliseconds for each operation, so an extra
-millisecond doesn't matter.
-
-On the other hand, why *not* make structured logging fast? The `SugaredLogger`
-isn't any harder to use than other logging packages, and the `Logger` makes
-structured logging possible in performance-sensitive contexts. Across a fleet
-of Go microservices, making each application even slightly more efficient adds
-up quickly.
-
-### Why aren't `Logger` and `SugaredLogger` interfaces?
-
-Unlike the familiar `io.Writer` and `http.Handler`, `Logger` and
-`SugaredLogger` interfaces would include *many* methods. As [Rob Pike points
-out][go-proverbs], "The bigger the interface, the weaker the abstraction."
-Interfaces are also rigid — *any* change requires releasing a new major
-version, since it breaks all third-party implementations.
-
-Making the `Logger` and `SugaredLogger` concrete types doesn't sacrifice much
-abstraction, and it lets us add methods without introducing breaking changes.
-Your applications should define and depend upon an interface that includes
-just the methods you use.
-
-### Why are some of my logs missing?
-
-Logs are dropped intentionally by zap when sampling is enabled. The production
-configuration (as returned by `NewProductionConfig()` enables sampling which will
-cause repeated logs within a second to be sampled. See more details on why sampling
-is enabled in [Why sample application logs](https://github.com/uber-go/zap/blob/master/FAQ.md#why-sample-application-logs).
-
-### Why sample application logs?
-
-Applications often experience runs of errors, either because of a bug or
-because of a misbehaving user. Logging errors is usually a good idea, but it
-can easily make this bad situation worse: not only is your application coping
-with a flood of errors, it's also spending extra CPU cycles and I/O logging
-those errors. Since writes are typically serialized, logging limits throughput
-when you need it most.
-
-Sampling fixes this problem by dropping repetitive log entries. Under normal
-conditions, your application writes out every entry. When similar entries are
-logged hundreds or thousands of times each second, though, zap begins dropping
-duplicates to preserve throughput.
-
-### Why do the structured logging APIs take a message in addition to fields?
-
-Subjectively, we find it helpful to accompany structured context with a brief
-description. This isn't critical during development, but it makes debugging
-and operating unfamiliar systems much easier.
-
-More concretely, zap's sampling algorithm uses the message to identify
-duplicate entries. In our experience, this is a practical middle ground
-between random sampling (which often drops the exact entry that you need while
-debugging) and hashing the complete entry (which is prohibitively expensive).
-
-### Why include package-global loggers?
-
-Since so many other logging packages include a global logger, many
-applications aren't designed to accept loggers as explicit parameters.
-Changing function signatures is often a breaking change, so zap includes
-global loggers to simplify migration.
-
-Avoid them where possible.
-
-### Why include dedicated Panic and Fatal log levels?
-
-In general, application code should handle errors gracefully instead of using
-`panic` or `os.Exit`. However, every rule has exceptions, and it's common to
-crash when an error is truly unrecoverable. To avoid losing any information
-— especially the reason for the crash — the logger must flush any
-buffered entries before the process exits.
-
-Zap makes this easy by offering `Panic` and `Fatal` logging methods that
-automatically flush before exiting. Of course, this doesn't guarantee that
-logs will never be lost, but it eliminates a common error.
-
-See the discussion in uber-go/zap#207 for more details.
-
-### What's `DPanic`?
-
-`DPanic` stands for "panic in development." In development, it logs at
-`PanicLevel`; otherwise, it logs at `ErrorLevel`. `DPanic` makes it easier to
-catch errors that are theoretically possible, but shouldn't actually happen,
-*without* crashing in production.
-
-If you've ever written code like this, you need `DPanic`:
-
-```go
-if err != nil {
-  panic(fmt.Sprintf("shouldn't ever get here: %v", err))
-}
-```
-
-## Installation
-
-### What does the error `expects import "go.uber.org/zap"` mean?
-
-Either zap was installed incorrectly or you're referencing the wrong package
-name in your code.
-
-Zap's source code happens to be hosted on GitHub, but the [import
-path][import-path] is `go.uber.org/zap`. This gives us, the project
-maintainers, the freedom to move the source code if necessary. However, it
-means that you need to take a little care when installing and using the
-package.
-
-If you follow two simple rules, everything should work: install zap with `go
-get -u go.uber.org/zap`, and always import it in your code with `import
-"go.uber.org/zap"`. Your code shouldn't contain *any* references to
-`github.com/uber-go/zap`.
-
-## Usage
-
-### Does zap support log rotation?
-
-Zap doesn't natively support rotating log files, since we prefer to leave this
-to an external program like `logrotate`.
-
-However, it's easy to integrate a log rotation package like
-[`gopkg.in/natefinch/lumberjack.v2`][lumberjack] as a `zapcore.WriteSyncer`.
-
-```go
-// lumberjack.Logger is already safe for concurrent use, so we don't need to
-// lock it.
-w := zapcore.AddSync(&lumberjack.Logger{
-  Filename:   "/var/log/myapp/foo.log",
-  MaxSize:    500, // megabytes
-  MaxBackups: 3,
-  MaxAge:     28, // days
-})
-core := zapcore.NewCore(
-  zapcore.NewJSONEncoder(zap.NewProductionEncoderConfig()),
-  w,
-  zap.InfoLevel,
-)
-logger := zap.New(core)
-```
-
-## Extensions
-
-We'd love to support every logging need within zap itself, but we're only
-familiar with a handful of log ingestion systems, flag-parsing packages, and
-the like. Rather than merging code that we can't effectively debug and
-support, we'd rather grow an ecosystem of zap extensions.
-
-We're aware of the following extensions, but haven't used them ourselves:
-
-| Package | Integration |
-| --- | --- |
-| `github.com/tchap/zapext` | Sentry, syslog |
-| `github.com/fgrosse/zaptest` | Ginkgo |
-| `github.com/blendle/zapdriver` | Stackdriver |
-| `github.com/moul/zapgorm` | Gorm |
-| `github.com/moul/zapfilter` | Advanced filtering rules |
-
-[go-proverbs]: https://go-proverbs.github.io/
-[import-path]: https://golang.org/cmd/go/#hdr-Remote_import_paths
-[lumberjack]: https://godoc.org/gopkg.in/natefinch/lumberjack.v2

data/vendor/go.uber.org/zap/LICENSE.txt

@@ -1,19 +0,0 @@
-Copyright (c) 2016-2017 Uber Technologies, Inc.
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in
-all copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
-THE SOFTWARE.

data/vendor/go.uber.org/zap/Makefile

@@ -1,73 +0,0 @@
-export GOBIN ?= $(shell pwd)/bin
-
-GOLINT = $(GOBIN)/golint
-STATICCHECK = $(GOBIN)/staticcheck
-BENCH_FLAGS ?= -cpuprofile=cpu.pprof -memprofile=mem.pprof -benchmem
-
-# Directories containing independent Go modules.
-#
-# We track coverage only for the main module.
-MODULE_DIRS = . ./benchmarks ./zapgrpc/internal/test
-
-# Many Go tools take file globs or directories as arguments instead of packages.
-GO_FILES := $(shell \
-	find . '(' -path '*/.*' -o -path './vendor' ')' -prune \
-	-o -name '*.go' -print | cut -b3-)
-
-.PHONY: all
-all: lint test
-
-.PHONY: lint
-lint: $(GOLINT) $(STATICCHECK)
-	@rm -rf lint.log
-	@echo "Checking formatting..."
-	@gofmt -d -s $(GO_FILES) 2>&1 | tee lint.log
-	@echo "Checking vet..."
-	@$(foreach dir,$(MODULE_DIRS),(cd $(dir) && go vet ./... 2>&1) &&) true | tee -a lint.log
-	@echo "Checking lint..."
-	@$(foreach dir,$(MODULE_DIRS),(cd $(dir) && $(GOLINT) ./... 2>&1) &&) true | tee -a lint.log
-	@echo "Checking staticcheck..."
-	@$(foreach dir,$(MODULE_DIRS),(cd $(dir) && $(STATICCHECK) ./... 2>&1) &&) true | tee -a lint.log
-	@echo "Checking for unresolved FIXMEs..."
-	@git grep -i fixme | grep -v -e Makefile | tee -a lint.log
-	@echo "Checking for license headers..."
-	@./checklicense.sh | tee -a lint.log
-	@[ ! -s lint.log ]
-	@echo "Checking 'go mod tidy'..."
-	@make tidy
-	@if ! git diff --quiet; then \
-		echo "'go mod tidy' resulted in changes or working tree is dirty:"; \
-		git --no-pager diff; \
-	fi
-
-$(GOLINT):
-	cd tools && go install golang.org/x/lint/golint
-
-$(STATICCHECK):
-	cd tools && go install honnef.co/go/tools/cmd/staticcheck
-
-.PHONY: test
-test:
-	@$(foreach dir,$(MODULE_DIRS),(cd $(dir) && go test -race ./...) &&) true
-
-.PHONY: cover
-cover:
-	go test -race -coverprofile=cover.out -coverpkg=./... ./...
-	go tool cover -html=cover.out -o cover.html
-
-.PHONY: bench
-BENCH ?= .
-bench:
-	@$(foreach dir,$(MODULE_DIRS), ( \
-		cd $(dir) && \
-		go list ./... | xargs -n1 go test -bench=$(BENCH) -run="^$$" $(BENCH_FLAGS) \
-	) &&) true
-
-.PHONY: updatereadme
-updatereadme:
-	rm -f README.md
-	cat .readme.tmpl | go run internal/readme/readme.go > README.md
-
-.PHONY: tidy
-tidy:
-	@$(foreach dir,$(MODULE_DIRS),(cd $(dir) && go mod tidy) &&) true

data/vendor/go.uber.org/zap/README.md

@@ -1,134 +0,0 @@
-# :zap: zap [![GoDoc][doc-img]][doc] [![Build Status][ci-img]][ci] [![Coverage Status][cov-img]][cov]
-
-Blazing fast, structured, leveled logging in Go.
-
-## Installation
-
-`go get -u go.uber.org/zap`
-
-Note that zap only supports the two most recent minor versions of Go.
-
-## Quick Start
-
-In contexts where performance is nice, but not critical, use the
-`SugaredLogger`. It's 4-10x faster than other structured logging
-packages and includes both structured and `printf`-style APIs.
-
-```go
-logger, _ := zap.NewProduction()
-defer logger.Sync() // flushes buffer, if any
-sugar := logger.Sugar()
-sugar.Infow("failed to fetch URL",
-  // Structured context as loosely typed key-value pairs.
-  "url", url,
-  "attempt", 3,
-  "backoff", time.Second,
-)
-sugar.Infof("Failed to fetch URL: %s", url)
-```
-
-When performance and type safety are critical, use the `Logger`. It's even
-faster than the `SugaredLogger` and allocates far less, but it only supports
-structured logging.
-
-```go
-logger, _ := zap.NewProduction()
-defer logger.Sync()
-logger.Info("failed to fetch URL",
-  // Structured context as strongly typed Field values.
-  zap.String("url", url),
-  zap.Int("attempt", 3),
-  zap.Duration("backoff", time.Second),
-)
-```
-
-See the [documentation][doc] and [FAQ](FAQ.md) for more details.
-
-## Performance
-
-For applications that log in the hot path, reflection-based serialization and
-string formatting are prohibitively expensive — they're CPU-intensive
-and make many small allocations. Put differently, using `encoding/json` and
-`fmt.Fprintf` to log tons of `interface{}`s makes your application slow.
-
-Zap takes a different approach. It includes a reflection-free, zero-allocation
-JSON encoder, and the base `Logger` strives to avoid serialization overhead
-and allocations wherever possible. By building the high-level `SugaredLogger`
-on that foundation, zap lets users *choose* when they need to count every
-allocation and when they'd prefer a more familiar, loosely typed API.
-
-As measured by its own [benchmarking suite][], not only is zap more performant
-than comparable structured logging packages — it's also faster than the
-standard library. Like all benchmarks, take these with a grain of salt.<sup
-id="anchor-versions">[1](#footnote-versions)</sup>
-
-Log a message and 10 fields:
-
-| Package | Time | Time % to zap | Objects Allocated |
-| :------ | :--: | :-----------: | :---------------: |
-| :zap: zap | 862 ns/op | +0% | 5 allocs/op
-| :zap: zap (sugared) | 1250 ns/op | +45% | 11 allocs/op
-| zerolog | 4021 ns/op | +366% | 76 allocs/op
-| go-kit | 4542 ns/op | +427% | 105 allocs/op
-| apex/log | 26785 ns/op | +3007% | 115 allocs/op
-| logrus | 29501 ns/op | +3322% | 125 allocs/op
-| log15 | 29906 ns/op | +3369% | 122 allocs/op
-
-Log a message with a logger that already has 10 fields of context:
-
-| Package | Time | Time % to zap | Objects Allocated |
-| :------ | :--: | :-----------: | :---------------: |
-| :zap: zap | 126 ns/op | +0% | 0 allocs/op
-| :zap: zap (sugared) | 187 ns/op | +48% | 2 allocs/op
-| zerolog | 88 ns/op | -30% | 0 allocs/op
-| go-kit | 5087 ns/op | +3937% | 103 allocs/op
-| log15 | 18548 ns/op | +14621% | 73 allocs/op
-| apex/log | 26012 ns/op | +20544% | 104 allocs/op
-| logrus | 27236 ns/op | +21516% | 113 allocs/op
-
-Log a static string, without any context or `printf`-style templating:
-
-| Package | Time | Time % to zap | Objects Allocated |
-| :------ | :--: | :-----------: | :---------------: |
-| :zap: zap | 118 ns/op | +0% | 0 allocs/op
-| :zap: zap (sugared) | 191 ns/op | +62% | 2 allocs/op
-| zerolog | 93 ns/op | -21% | 0 allocs/op
-| go-kit | 280 ns/op | +137% | 11 allocs/op
-| standard library | 499 ns/op | +323% | 2 allocs/op
-| apex/log | 1990 ns/op | +1586% | 10 allocs/op
-| logrus | 3129 ns/op | +2552% | 24 allocs/op
-| log15 | 3887 ns/op | +3194% | 23 allocs/op
-
-## Development Status: Stable
-
-All APIs are finalized, and no breaking changes will be made in the 1.x series
-of releases. Users of semver-aware dependency management systems should pin
-zap to `^1`.
-
-## Contributing
-
-We encourage and support an active, healthy community of contributors &mdash;
-including you! Details are in the [contribution guide](CONTRIBUTING.md) and
-the [code of conduct](CODE_OF_CONDUCT.md). The zap maintainers keep an eye on
-issues and pull requests, but you can also report any negative conduct to
-oss-conduct@uber.com. That email list is a private, safe space; even the zap
-maintainers don't have access, so don't hesitate to hold us to a high
-standard.
-
-<hr>
-
-Released under the [MIT License](LICENSE.txt).
-
-<sup id="footnote-versions">1</sup> In particular, keep in mind that we may be
-benchmarking against slightly older versions of other packages. Versions are
-pinned in the [benchmarks/go.mod][] file. [↩](#anchor-versions)
-
-[doc-img]: https://pkg.go.dev/badge/go.uber.org/zap
-[doc]: https://pkg.go.dev/go.uber.org/zap
-[ci-img]: https://github.com/uber-go/zap/actions/workflows/go.yml/badge.svg
-[ci]: https://github.com/uber-go/zap/actions/workflows/go.yml
-[cov-img]: https://codecov.io/gh/uber-go/zap/branch/master/graph/badge.svg
-[cov]: https://codecov.io/gh/uber-go/zap
-[benchmarking suite]: https://github.com/uber-go/zap/tree/master/benchmarks
-[benchmarks/go.mod]: https://github.com/uber-go/zap/blob/master/benchmarks/go.mod
-