From 6cbf127604c695eeb0caac223d61d1a3ccf00116 Mon Sep 17 00:00:00 2001 From: simitt Date: Mon, 16 Jul 2018 15:14:45 +0200 Subject: [PATCH 1/6] Update pflag to v1.0.1 --- NOTICE.txt | 1 + .../elastic/beats/libbeat/cmd/setup.go | 2 +- vendor/github.com/spf13/pflag/bytes.go | 105 ++++++++++++++ .../github.com/spf13/pflag/duration_slice.go | 128 ++++++++++++++++++ vendor/github.com/spf13/pflag/flag.go | 98 +++++++++++--- vendor/github.com/spf13/pflag/golangflag.go | 4 + vendor/github.com/spf13/pflag/string_array.go | 8 +- vendor/github.com/spf13/pflag/string_slice.go | 20 +++ vendor/vendor.json | 13 +- 9 files changed, 355 insertions(+), 24 deletions(-) create mode 100644 vendor/github.com/spf13/pflag/bytes.go create mode 100644 vendor/github.com/spf13/pflag/duration_slice.go diff --git a/NOTICE.txt b/NOTICE.txt index 0f2103aef7..670b56fad8 100644 --- a/NOTICE.txt +++ b/NOTICE.txt @@ -1694,6 +1694,7 @@ Apache License 2.0 -------------------------------------------------------------------- Dependency: github.com/spf13/pflag +Version: v1.0.1 Revision: e57e3eeb33f795204c1ca35f56c44f83227c6e66 License type (autodetected): BSD-3-Clause ./vendor/github.com/spf13/pflag/LICENSE: diff --git a/vendor/github.com/elastic/beats/libbeat/cmd/setup.go b/vendor/github.com/elastic/beats/libbeat/cmd/setup.go index d8745cf765..67343507cb 100644 --- a/vendor/github.com/elastic/beats/libbeat/cmd/setup.go +++ b/vendor/github.com/elastic/beats/libbeat/cmd/setup.go @@ -34,7 +34,7 @@ func genSetupCmd(name, idxPrefix, version string, beatCreator beat.Creator) *cob Long: `This command does initial setup of the environment: * Index mapping template in Elasticsearch to ensure fields are mapped. - * Kibana dashboards (where available). + * Kibana dashboards and index patterns (where available). * ML jobs (where available). * Ingest pipelines (where available). `, diff --git a/vendor/github.com/spf13/pflag/bytes.go b/vendor/github.com/spf13/pflag/bytes.go new file mode 100644 index 0000000000..12c58db9fe --- /dev/null +++ b/vendor/github.com/spf13/pflag/bytes.go @@ -0,0 +1,105 @@ +package pflag + +import ( + "encoding/hex" + "fmt" + "strings" +) + +// BytesHex adapts []byte for use as a flag. Value of flag is HEX encoded +type bytesHexValue []byte + +func (bytesHex bytesHexValue) String() string { + return fmt.Sprintf("%X", []byte(bytesHex)) +} + +func (bytesHex *bytesHexValue) Set(value string) error { + bin, err := hex.DecodeString(strings.TrimSpace(value)) + + if err != nil { + return err + } + + *bytesHex = bin + + return nil +} + +func (*bytesHexValue) Type() string { + return "bytesHex" +} + +func newBytesHexValue(val []byte, p *[]byte) *bytesHexValue { + *p = val + return (*bytesHexValue)(p) +} + +func bytesHexConv(sval string) (interface{}, error) { + + bin, err := hex.DecodeString(sval) + + if err == nil { + return bin, nil + } + + return nil, fmt.Errorf("invalid string being converted to Bytes: %s %s", sval, err) +} + +// GetBytesHex return the []byte value of a flag with the given name +func (f *FlagSet) GetBytesHex(name string) ([]byte, error) { + val, err := f.getFlagType(name, "bytesHex", bytesHexConv) + + if err != nil { + return []byte{}, err + } + + return val.([]byte), nil +} + +// BytesHexVar defines an []byte flag with specified name, default value, and usage string. +// The argument p points to an []byte variable in which to store the value of the flag. +func (f *FlagSet) BytesHexVar(p *[]byte, name string, value []byte, usage string) { + f.VarP(newBytesHexValue(value, p), name, "", usage) +} + +// BytesHexVarP is like BytesHexVar, but accepts a shorthand letter that can be used after a single dash. +func (f *FlagSet) BytesHexVarP(p *[]byte, name, shorthand string, value []byte, usage string) { + f.VarP(newBytesHexValue(value, p), name, shorthand, usage) +} + +// BytesHexVar defines an []byte flag with specified name, default value, and usage string. +// The argument p points to an []byte variable in which to store the value of the flag. +func BytesHexVar(p *[]byte, name string, value []byte, usage string) { + CommandLine.VarP(newBytesHexValue(value, p), name, "", usage) +} + +// BytesHexVarP is like BytesHexVar, but accepts a shorthand letter that can be used after a single dash. +func BytesHexVarP(p *[]byte, name, shorthand string, value []byte, usage string) { + CommandLine.VarP(newBytesHexValue(value, p), name, shorthand, usage) +} + +// BytesHex defines an []byte flag with specified name, default value, and usage string. +// The return value is the address of an []byte variable that stores the value of the flag. +func (f *FlagSet) BytesHex(name string, value []byte, usage string) *[]byte { + p := new([]byte) + f.BytesHexVarP(p, name, "", value, usage) + return p +} + +// BytesHexP is like BytesHex, but accepts a shorthand letter that can be used after a single dash. +func (f *FlagSet) BytesHexP(name, shorthand string, value []byte, usage string) *[]byte { + p := new([]byte) + f.BytesHexVarP(p, name, shorthand, value, usage) + return p +} + +// BytesHex defines an []byte flag with specified name, default value, and usage string. +// The return value is the address of an []byte variable that stores the value of the flag. +func BytesHex(name string, value []byte, usage string) *[]byte { + return CommandLine.BytesHexP(name, "", value, usage) +} + +// BytesHexP is like BytesHex, but accepts a shorthand letter that can be used after a single dash. +func BytesHexP(name, shorthand string, value []byte, usage string) *[]byte { + return CommandLine.BytesHexP(name, shorthand, value, usage) +} diff --git a/vendor/github.com/spf13/pflag/duration_slice.go b/vendor/github.com/spf13/pflag/duration_slice.go new file mode 100644 index 0000000000..52c6b6dc10 --- /dev/null +++ b/vendor/github.com/spf13/pflag/duration_slice.go @@ -0,0 +1,128 @@ +package pflag + +import ( + "fmt" + "strings" + "time" +) + +// -- durationSlice Value +type durationSliceValue struct { + value *[]time.Duration + changed bool +} + +func newDurationSliceValue(val []time.Duration, p *[]time.Duration) *durationSliceValue { + dsv := new(durationSliceValue) + dsv.value = p + *dsv.value = val + return dsv +} + +func (s *durationSliceValue) Set(val string) error { + ss := strings.Split(val, ",") + out := make([]time.Duration, len(ss)) + for i, d := range ss { + var err error + out[i], err = time.ParseDuration(d) + if err != nil { + return err + } + + } + if !s.changed { + *s.value = out + } else { + *s.value = append(*s.value, out...) + } + s.changed = true + return nil +} + +func (s *durationSliceValue) Type() string { + return "durationSlice" +} + +func (s *durationSliceValue) String() string { + out := make([]string, len(*s.value)) + for i, d := range *s.value { + out[i] = fmt.Sprintf("%s", d) + } + return "[" + strings.Join(out, ",") + "]" +} + +func durationSliceConv(val string) (interface{}, error) { + val = strings.Trim(val, "[]") + // Empty string would cause a slice with one (empty) entry + if len(val) == 0 { + return []time.Duration{}, nil + } + ss := strings.Split(val, ",") + out := make([]time.Duration, len(ss)) + for i, d := range ss { + var err error + out[i], err = time.ParseDuration(d) + if err != nil { + return nil, err + } + + } + return out, nil +} + +// GetDurationSlice returns the []time.Duration value of a flag with the given name +func (f *FlagSet) GetDurationSlice(name string) ([]time.Duration, error) { + val, err := f.getFlagType(name, "durationSlice", durationSliceConv) + if err != nil { + return []time.Duration{}, err + } + return val.([]time.Duration), nil +} + +// DurationSliceVar defines a durationSlice flag with specified name, default value, and usage string. +// The argument p points to a []time.Duration variable in which to store the value of the flag. +func (f *FlagSet) DurationSliceVar(p *[]time.Duration, name string, value []time.Duration, usage string) { + f.VarP(newDurationSliceValue(value, p), name, "", usage) +} + +// DurationSliceVarP is like DurationSliceVar, but accepts a shorthand letter that can be used after a single dash. +func (f *FlagSet) DurationSliceVarP(p *[]time.Duration, name, shorthand string, value []time.Duration, usage string) { + f.VarP(newDurationSliceValue(value, p), name, shorthand, usage) +} + +// DurationSliceVar defines a duration[] flag with specified name, default value, and usage string. +// The argument p points to a duration[] variable in which to store the value of the flag. +func DurationSliceVar(p *[]time.Duration, name string, value []time.Duration, usage string) { + CommandLine.VarP(newDurationSliceValue(value, p), name, "", usage) +} + +// DurationSliceVarP is like DurationSliceVar, but accepts a shorthand letter that can be used after a single dash. +func DurationSliceVarP(p *[]time.Duration, name, shorthand string, value []time.Duration, usage string) { + CommandLine.VarP(newDurationSliceValue(value, p), name, shorthand, usage) +} + +// DurationSlice defines a []time.Duration flag with specified name, default value, and usage string. +// The return value is the address of a []time.Duration variable that stores the value of the flag. +func (f *FlagSet) DurationSlice(name string, value []time.Duration, usage string) *[]time.Duration { + p := []time.Duration{} + f.DurationSliceVarP(&p, name, "", value, usage) + return &p +} + +// DurationSliceP is like DurationSlice, but accepts a shorthand letter that can be used after a single dash. +func (f *FlagSet) DurationSliceP(name, shorthand string, value []time.Duration, usage string) *[]time.Duration { + p := []time.Duration{} + f.DurationSliceVarP(&p, name, shorthand, value, usage) + return &p +} + +// DurationSlice defines a []time.Duration flag with specified name, default value, and usage string. +// The return value is the address of a []time.Duration variable that stores the value of the flag. +func DurationSlice(name string, value []time.Duration, usage string) *[]time.Duration { + return CommandLine.DurationSliceP(name, "", value, usage) +} + +// DurationSliceP is like DurationSlice, but accepts a shorthand letter that can be used after a single dash. +func DurationSliceP(name, shorthand string, value []time.Duration, usage string) *[]time.Duration { + return CommandLine.DurationSliceP(name, shorthand, value, usage) +} diff --git a/vendor/github.com/spf13/pflag/flag.go b/vendor/github.com/spf13/pflag/flag.go index 28538c0750..5eadc84e3c 100644 --- a/vendor/github.com/spf13/pflag/flag.go +++ b/vendor/github.com/spf13/pflag/flag.go @@ -101,6 +101,7 @@ package pflag import ( "bytes" "errors" + goflag "flag" "fmt" "io" "os" @@ -123,6 +124,12 @@ const ( PanicOnError ) +// ParseErrorsWhitelist defines the parsing errors that can be ignored +type ParseErrorsWhitelist struct { + // UnknownFlags will ignore unknown flags errors and continue parsing rest of the flags + UnknownFlags bool +} + // NormalizedName is a flag name that has been normalized according to rules // for the FlagSet (e.g. making '-' and '_' equivalent). type NormalizedName string @@ -138,6 +145,9 @@ type FlagSet struct { // help/usage messages. SortFlags bool + // ParseErrorsWhitelist is used to configure a whitelist of errors + ParseErrorsWhitelist ParseErrorsWhitelist + name string parsed bool actual map[NormalizedName]*Flag @@ -153,6 +163,8 @@ type FlagSet struct { output io.Writer // nil means stderr; use out() accessor interspersed bool // allow interspersed option/non-option args normalizeNameFunc func(f *FlagSet, name string) NormalizedName + + addedGoFlagSets []*goflag.FlagSet } // A Flag represents the state of a flag. @@ -267,16 +279,16 @@ func (f *FlagSet) VisitAll(fn func(*Flag)) { } } -// HasFlags returns a bool to indicate if the FlagSet has any flags definied. +// HasFlags returns a bool to indicate if the FlagSet has any flags defined. func (f *FlagSet) HasFlags() bool { return len(f.formal) > 0 } // HasAvailableFlags returns a bool to indicate if the FlagSet has any flags -// definied that are not hidden or deprecated. +// that are not hidden. func (f *FlagSet) HasAvailableFlags() bool { for _, flag := range f.formal { - if !flag.Hidden && len(flag.Deprecated) == 0 { + if !flag.Hidden { return true } } @@ -386,6 +398,7 @@ func (f *FlagSet) MarkDeprecated(name string, usageMessage string) error { return fmt.Errorf("deprecated message for flag %q must be set", name) } flag.Deprecated = usageMessage + flag.Hidden = true return nil } @@ -586,11 +599,14 @@ func wrapN(i, slop int, s string) (string, string) { return s, "" } - w := strings.LastIndexAny(s[:i], " \t") + w := strings.LastIndexAny(s[:i], " \t\n") if w <= 0 { return s, "" } - + nlPos := strings.LastIndex(s[:i], "\n") + if nlPos > 0 && nlPos < w { + return s[:nlPos], s[nlPos+1:] + } return s[:w], s[w+1:] } @@ -599,7 +615,7 @@ func wrapN(i, slop int, s string) (string, string) { // caller). Pass `w` == 0 to do no wrapping func wrap(i, w int, s string) string { if w == 0 { - return s + return strings.Replace(s, "\n", "\n"+strings.Repeat(" ", i), -1) } // space between indent i and end of line width w into which @@ -617,7 +633,7 @@ func wrap(i, w int, s string) string { } // If still not enough space then don't even try to wrap. if wrap < 24 { - return s + return strings.Replace(s, "\n", r, -1) } // Try to avoid short orphan words on the final line, by @@ -629,14 +645,14 @@ func wrap(i, w int, s string) string { // Handle first line, which is indented by the caller (or the // special case above) l, s = wrapN(wrap, slop, s) - r = r + l + r = r + strings.Replace(l, "\n", "\n"+strings.Repeat(" ", i), -1) // Now wrap the rest for s != "" { var t string t, s = wrapN(wrap, slop, s) - r = r + "\n" + strings.Repeat(" ", i) + t + r = r + "\n" + strings.Repeat(" ", i) + strings.Replace(t, "\n", "\n"+strings.Repeat(" ", i), -1) } return r @@ -653,7 +669,7 @@ func (f *FlagSet) FlagUsagesWrapped(cols int) string { maxlen := 0 f.VisitAll(func(flag *Flag) { - if flag.Deprecated != "" || flag.Hidden { + if flag.Hidden { return } @@ -700,6 +716,9 @@ func (f *FlagSet) FlagUsagesWrapped(cols int) string { line += fmt.Sprintf(" (default %s)", flag.DefValue) } } + if len(flag.Deprecated) != 0 { + line += fmt.Sprintf(" (DEPRECATED: %s)", flag.Deprecated) + } lines = append(lines, line) }) @@ -896,6 +915,25 @@ func (f *FlagSet) usage() { } } +//--unknown (args will be empty) +//--unknown --next-flag ... (args will be --next-flag ...) +//--unknown arg ... (args will be arg ...) +func stripUnknownFlagValue(args []string) []string { + if len(args) == 0 { + //--unknown + return args + } + + first := args[0] + if first[0] == '-' { + //--unknown --next-flag ... + return args + } + + //--unknown arg ... (args will be arg ...) + return args[1:] +} + func (f *FlagSet) parseLongArg(s string, args []string, fn parseFunc) (a []string, err error) { a = args name := s[2:] @@ -907,13 +945,24 @@ func (f *FlagSet) parseLongArg(s string, args []string, fn parseFunc) (a []strin split := strings.SplitN(name, "=", 2) name = split[0] flag, exists := f.formal[f.normalizeFlagName(name)] + if !exists { - if name == "help" { // special case for nice help message. + switch { + case name == "help": f.usage() return a, ErrHelp + case f.ParseErrorsWhitelist.UnknownFlags: + // --unknown=unknownval arg ... + // we do not want to lose arg in this case + if len(split) >= 2 { + return a, nil + } + + return stripUnknownFlagValue(a), nil + default: + err = f.failf("unknown flag: --%s", name) + return } - err = f.failf("unknown flag: --%s", name) - return } var value string @@ -951,13 +1000,25 @@ func (f *FlagSet) parseSingleShortArg(shorthands string, args []string, fn parse flag, exists := f.shorthands[c] if !exists { - if c == 'h' { // special case for nice help message. + switch { + case c == 'h': f.usage() err = ErrHelp return + case f.ParseErrorsWhitelist.UnknownFlags: + // '-f=arg arg ...' + // we do not want to lose arg in this case + if len(shorthands) > 2 && shorthands[1] == '=' { + outShorts = "" + return + } + + outArgs = stripUnknownFlagValue(outArgs) + return + default: + err = f.failf("unknown shorthand flag: %q in -%s", c, shorthands) + return } - err = f.failf("unknown shorthand flag: %q in -%s", c, shorthands) - return } var value string @@ -1044,6 +1105,11 @@ func (f *FlagSet) parseArgs(args []string, fn parseFunc) (err error) { // are defined and before flags are accessed by the program. // The return value will be ErrHelp if -help was set but not defined. func (f *FlagSet) Parse(arguments []string) error { + if f.addedGoFlagSets != nil { + for _, goFlagSet := range f.addedGoFlagSets { + goFlagSet.Parse(nil) + } + } f.parsed = true if len(arguments) < 0 { diff --git a/vendor/github.com/spf13/pflag/golangflag.go b/vendor/github.com/spf13/pflag/golangflag.go index c4f47ebe59..d3dd72b7fe 100644 --- a/vendor/github.com/spf13/pflag/golangflag.go +++ b/vendor/github.com/spf13/pflag/golangflag.go @@ -98,4 +98,8 @@ func (f *FlagSet) AddGoFlagSet(newSet *goflag.FlagSet) { newSet.VisitAll(func(goflag *goflag.Flag) { f.AddGoFlag(goflag) }) + if f.addedGoFlagSets == nil { + f.addedGoFlagSets = make([]*goflag.FlagSet, 0) + } + f.addedGoFlagSets = append(f.addedGoFlagSets, newSet) } diff --git a/vendor/github.com/spf13/pflag/string_array.go b/vendor/github.com/spf13/pflag/string_array.go index 276b7ed49e..fa7bc60187 100644 --- a/vendor/github.com/spf13/pflag/string_array.go +++ b/vendor/github.com/spf13/pflag/string_array.go @@ -52,7 +52,7 @@ func (f *FlagSet) GetStringArray(name string) ([]string, error) { // StringArrayVar defines a string flag with specified name, default value, and usage string. // The argument p points to a []string variable in which to store the values of the multiple flags. -// The value of each argument will not try to be separated by comma +// The value of each argument will not try to be separated by comma. Use a StringSlice for that. func (f *FlagSet) StringArrayVar(p *[]string, name string, value []string, usage string) { f.VarP(newStringArrayValue(value, p), name, "", usage) } @@ -64,7 +64,7 @@ func (f *FlagSet) StringArrayVarP(p *[]string, name, shorthand string, value []s // StringArrayVar defines a string flag with specified name, default value, and usage string. // The argument p points to a []string variable in which to store the value of the flag. -// The value of each argument will not try to be separated by comma +// The value of each argument will not try to be separated by comma. Use a StringSlice for that. func StringArrayVar(p *[]string, name string, value []string, usage string) { CommandLine.VarP(newStringArrayValue(value, p), name, "", usage) } @@ -76,7 +76,7 @@ func StringArrayVarP(p *[]string, name, shorthand string, value []string, usage // StringArray defines a string flag with specified name, default value, and usage string. // The return value is the address of a []string variable that stores the value of the flag. -// The value of each argument will not try to be separated by comma +// The value of each argument will not try to be separated by comma. Use a StringSlice for that. func (f *FlagSet) StringArray(name string, value []string, usage string) *[]string { p := []string{} f.StringArrayVarP(&p, name, "", value, usage) @@ -92,7 +92,7 @@ func (f *FlagSet) StringArrayP(name, shorthand string, value []string, usage str // StringArray defines a string flag with specified name, default value, and usage string. // The return value is the address of a []string variable that stores the value of the flag. -// The value of each argument will not try to be separated by comma +// The value of each argument will not try to be separated by comma. Use a StringSlice for that. func StringArray(name string, value []string, usage string) *[]string { return CommandLine.StringArrayP(name, "", value, usage) } diff --git a/vendor/github.com/spf13/pflag/string_slice.go b/vendor/github.com/spf13/pflag/string_slice.go index 05eee75438..0cd3ccc083 100644 --- a/vendor/github.com/spf13/pflag/string_slice.go +++ b/vendor/github.com/spf13/pflag/string_slice.go @@ -82,6 +82,11 @@ func (f *FlagSet) GetStringSlice(name string) ([]string, error) { // StringSliceVar defines a string flag with specified name, default value, and usage string. // The argument p points to a []string variable in which to store the value of the flag. +// Compared to StringArray flags, StringSlice flags take comma-separated value as arguments and split them accordingly. +// For example: +// --ss="v1,v2" -ss="v3" +// will result in +// []string{"v1", "v2", "v3"} func (f *FlagSet) StringSliceVar(p *[]string, name string, value []string, usage string) { f.VarP(newStringSliceValue(value, p), name, "", usage) } @@ -93,6 +98,11 @@ func (f *FlagSet) StringSliceVarP(p *[]string, name, shorthand string, value []s // StringSliceVar defines a string flag with specified name, default value, and usage string. // The argument p points to a []string variable in which to store the value of the flag. +// Compared to StringArray flags, StringSlice flags take comma-separated value as arguments and split them accordingly. +// For example: +// --ss="v1,v2" -ss="v3" +// will result in +// []string{"v1", "v2", "v3"} func StringSliceVar(p *[]string, name string, value []string, usage string) { CommandLine.VarP(newStringSliceValue(value, p), name, "", usage) } @@ -104,6 +114,11 @@ func StringSliceVarP(p *[]string, name, shorthand string, value []string, usage // StringSlice defines a string flag with specified name, default value, and usage string. // The return value is the address of a []string variable that stores the value of the flag. +// Compared to StringArray flags, StringSlice flags take comma-separated value as arguments and split them accordingly. +// For example: +// --ss="v1,v2" -ss="v3" +// will result in +// []string{"v1", "v2", "v3"} func (f *FlagSet) StringSlice(name string, value []string, usage string) *[]string { p := []string{} f.StringSliceVarP(&p, name, "", value, usage) @@ -119,6 +134,11 @@ func (f *FlagSet) StringSliceP(name, shorthand string, value []string, usage str // StringSlice defines a string flag with specified name, default value, and usage string. // The return value is the address of a []string variable that stores the value of the flag. +// Compared to StringArray flags, StringSlice flags take comma-separated value as arguments and split them accordingly. +// For example: +// --ss="v1,v2" -ss="v3" +// will result in +// []string{"v1", "v2", "v3"} func StringSlice(name string, value []string, usage string) *[]string { return CommandLine.StringSliceP(name, "", value, usage) } diff --git a/vendor/vendor.json b/vendor/vendor.json index 4fb5f7a127..c2db12d535 100644 --- a/vendor/vendor.json +++ b/vendor/vendor.json @@ -1835,10 +1835,12 @@ "revisionTime": "2017-11-23T00:13:03Z" }, { - "checksumSHA1": "fKq6NiaqP3DFxnCRF5mmpJWTSUA=", + "checksumSHA1": "k5TsfhX2vvfffYbZQ4fMKtL5+cA=", "path": "github.com/spf13/pflag", - "revision": "4c012f6dcd9546820e378d0bdda4d8fc772cdfea", - "revisionTime": "2017-11-06T14:28:49Z" + "revision": "583c0c0531f06d5278b7d917446061adc344b5cd", + "revisionTime": "2018-04-12T12:09:13Z", + "version": "v1.0.1", + "versionExact": "v1.0.1" }, { "checksumSHA1": "Le1psgZO0t6mRg6oY5dmnjH13hk=", @@ -2105,6 +2107,11 @@ "path": "howett.net/plist", "revision": "84d08b7bddb35583bb3153b811c6cc52bb306f52", "revisionTime": "2018-02-14T08:12:42Z" + }, + { + "path": "https://github.com/spf13/pflag", + "revision": "v1.0.1", + "version": "v1.0.1" } ], "rootPath": "github.com/elastic/apm-server" From a19598925726beffff476f2e4e49393580b15aac Mon Sep 17 00:00:00 2001 From: simitt Date: Fri, 20 Jul 2018 16:33:45 +0200 Subject: [PATCH 2/6] update beats docs. --- .../command-reference.asciidoc | 8 ++++- docs/copied-from-beats/dashboards.asciidoc | 7 ++-- docs/copied-from-beats/shared-docker.asciidoc | 36 +++++++++++++------ .../template-config.asciidoc | 12 +++++++ 4 files changed, 50 insertions(+), 13 deletions(-) diff --git a/docs/copied-from-beats/command-reference.asciidoc b/docs/copied-from-beats/command-reference.asciidoc index 2392ffb537..346679fda6 100644 --- a/docs/copied-from-beats/command-reference.asciidoc +++ b/docs/copied-from-beats/command-reference.asciidoc @@ -453,7 +453,10 @@ environment without actually running {beatname_uc} and ingesting data. *FLAGS* *`--dashboards`*:: -Sets up the Kibana dashboards only. +Sets up the Kibana dashboards only. This option loads the dashboards from the +{beatname_uc} package. For more options, such as loading customized dashboards, +see {beatsdevguide}/import-dashboards.html[Importing Existing Beat Dashboards] +in the _Beats Developer Guide_. *`-h, --help`*:: Shows help for the `setup` command. @@ -467,6 +470,9 @@ ifeval::["{beatname_lc}"=="filebeat"] Specifies a comma-separated list of modules. Use this flag to avoid errors when there are no modules defined in the +{beatname_lc}.yml+ file. +*`--pipelines`*:: +Sets up ingest pipelines for configured filesets. + endif::[] *`--template`*:: diff --git a/docs/copied-from-beats/dashboards.asciidoc b/docs/copied-from-beats/dashboards.asciidoc index 80d78bfea3..b82bf1fdfe 100644 --- a/docs/copied-from-beats/dashboards.asciidoc +++ b/docs/copied-from-beats/dashboards.asciidoc @@ -18,14 +18,17 @@ command (as described here) or +{beatname_lc}.yml+ config file. This requires a Kibana endpoint configuration. If you didn't already configure -a Kibana endpoint, see <<{beatname_lc}-configuration,configure {beatname_uc}>>. +a Kibana endpoint, see <<{beatname_lc}-configuration,configure {beatname_uc}>>. Make sure Kibana is running before you perform this step. If you are accessing a secured Kibana instance, make sure you've configured credentials as described in <<{beatname_lc}-configuration>>. To set up the Kibana dashboards for {beatname_uc}, use the appropriate command -for your system. +for your system. The command shown here loads the dashboards from the {beatname_uc} +package. For more options, such as loading customized dashboards, see +{beatsdevguide}/import-dashboards.html[Importing Existing Beat Dashboards] in +the _Beats Developer Guide_. ifndef::only-elasticsearch[] If you've configured the Logstash output, see <>. diff --git a/docs/copied-from-beats/shared-docker.asciidoc b/docs/copied-from-beats/shared-docker.asciidoc index 0460dd4ad5..0969d73b51 100644 --- a/docs/copied-from-beats/shared-docker.asciidoc +++ b/docs/copied-from-beats/shared-docker.asciidoc @@ -2,7 +2,23 @@ === Running {beatname_uc} on Docker Docker images for {beatname_uc} are available from the Elastic Docker -registry. You can retrieve an image with a `docker pull` command. +registry. The base image is https://hub.docker.com/_/centos/[centos:7]. + +A list of all published Docker images and tags is available at +https://www.docker.elastic.co[www.docker.elastic.co]. The source code is in +{dockergithub}[GitHub]. + +These images are free to use under the Elastic license. They contain open source +and free commercial features and access to paid commercial features. +{xpack-ref}/license-management.html[Start a 30-day trial] to try out all of the +paid commercial features. See the +https://www.elastic.co/subscriptions[Subscriptions] page for information about +Elastic license levels. + +==== Pulling the image + +Obtaining Beats for Docker is as simple as issuing a +docker pull+ command +against the Elastic Docker registry. ifeval::["{release-state}"=="unreleased"] @@ -18,30 +34,30 @@ ifeval::["{release-state}"!="unreleased"] docker pull {dockerimage} ------------------------------------------------ -endif::[] +Alternatively, you can download other Docker images that contain only features +available under the Apache 2.0 license. To download the images, go to +https://www.docker.elastic.co[www.docker.elastic.co]. -The base image is https://hub.docker.com/_/centos/[centos:7] and the source -code can be found on -{dockergithub}[GitHub]. +endif::[] [float] ==== Configure {beatname_uc} on Docker The Docker image provides several methods for configuring {beatname_uc}. The -conventional approach is to provide a configuration file via a bind-mounted -volume, but it's also possible to create a custom image with your +conventional approach is to provide a configuration file via a bind mount, but +it's also possible to create a custom image with your configuration included. [float] ===== Bind-mounted configuration -One way to configure {beatname_uc} on Docker is to provide +{beatname_lc}.yml+ via bind-mounting. -With +docker run+, the bind-mount can be specified like this: +One way to configure {beatname_uc} on Docker is to provide +{beatname_lc}.yml+ via a bind mount. +With +docker run+, the bind mount can be specified like this: ["source", "sh", subs="attributes"] -------------------------------------------- docker run \ - -v ~/{beatname_lc}.yml:/usr/share/{beatname_lc}/{beatname_lc}.yml \ + --mount type=bind,source="$(pwd)"/{beatname_lc}.yml,target=/usr/share/{beatname_lc}/{beatname_lc}.yml \ {dockerimage} -------------------------------------------- diff --git a/docs/copied-from-beats/template-config.asciidoc b/docs/copied-from-beats/template-config.asciidoc index 1eb590a091..354e90f100 100644 --- a/docs/copied-from-beats/template-config.asciidoc +++ b/docs/copied-from-beats/template-config.asciidoc @@ -87,4 +87,16 @@ ifeval::["{beatname_lc}"!="apm-server"] NOTE: With append_fields only new fields can be added an no existing one overwritten or changed. This is especially useful if data is collected through the http/json metricset where the data structure is not known in advance. Changing the config of append_fields means the template has to be overwritten and only applies to new indices. If there are 2 Beats with different append_fields configs the last one writing the template will win. Any changes will also have an affect on the Kibana Index pattern. +*`setup.template.json.enabled`*:: Set to true to load a json based template file. Specify the path to your Elasticsearch +index template file and set the name of the template. experimental[] + +["source","yaml",subs="attributes"] +---------------------------------------------------------------------- +setup.template.json.enabled: true +setup.template.json.path: "template.json" +setup.template.json.name: "template-name +---------------------------------------------------------------------- + +NOTE: If the JSON template is used, the fields.yml is skipped for the template generation. + endif::[] From e1e76d0ce0d6845ec68a21946d778c35a2ce74e8 Mon Sep 17 00:00:00 2001 From: simitt Date: Mon, 16 Jul 2018 15:50:38 +0200 Subject: [PATCH 3/6] deprecate setup cmd. --- cmd/root.go | 2 ++ 1 file changed, 2 insertions(+) diff --git a/cmd/root.go b/cmd/root.go index 7cdf933165..9e961d5bf7 100644 --- a/cmd/root.go +++ b/cmd/root.go @@ -37,4 +37,6 @@ var RootCmd *cmd.BeatsRootCmd func init() { var runFlags = pflag.NewFlagSet(Name, pflag.ExitOnError) RootCmd = cmd.GenRootCmdWithIndexPrefixWithRunFlags(Name, IdxPattern, "", beater.New, runFlags) + RootCmd.RunCmd.Flags().MarkDeprecated("setup", "use Kibana UI for initial setup.") + RootCmd.SetupCmd.Deprecated = "use Kibana UI for initial setup." } From 7722182e743df4d8d2316c28bccacaad4a59aa07 Mon Sep 17 00:00:00 2001 From: simitt Date: Mon, 16 Jul 2018 14:41:25 +0200 Subject: [PATCH 4/6] Docs: deprecate loading dashboards and index pattern. Add deprecation notes to apm-server.yml and docs for loading dashboards and index patterns via Kibana. Add deprecation note for setting up Kibana endpoint as it won't be needed any more. implements #1135 --- CHANGELOG.asciidoc | 1 + _meta/beat.yml | 95 ++++++++++--------- apm-server.yml | 95 ++++++++++--------- docs/configuring.asciidoc | 4 +- .../command-reference.asciidoc | 64 +++++++++++-- .../dashboardsconfig.asciidoc | 2 +- docs/copied-from-beats/outputconfig.asciidoc | 17 +++- .../shared-kibana-config.asciidoc | 2 +- .../shared-ssl-config.asciidoc | 2 + .../shared-template-load.asciidoc | 19 ++++ docs/dashboards.asciidoc | 50 +++++++++- docs/guide/index.asciidoc | 12 +-- docs/index.asciidoc | 1 + docs/setting-up-and-running.asciidoc | 18 ---- 14 files changed, 252 insertions(+), 130 deletions(-) diff --git a/CHANGELOG.asciidoc b/CHANGELOG.asciidoc index d0b4bc1120..7410f74ea4 100644 --- a/CHANGELOG.asciidoc +++ b/CHANGELOG.asciidoc @@ -24,6 +24,7 @@ https://github.com/elastic/apm-server/compare/6.3\...master[View commits] - Add source_mapping.elasticsearch configuration option {pull}1114[1114]. - Add /v1/metrics endpoint {pull}1000[1000] {pull}1121[1121]. - Push onboarding doc to separate ES index {pull}1159[1159]. +- Deprecate usage of `apm-server setup` {pull}1142[1142]. [[release-notes-6.3]] diff --git a/_meta/beat.yml b/_meta/beat.yml index bf1b0340ea..1b8bc98cbd 100644 --- a/_meta/beat.yml +++ b/_meta/beat.yml @@ -155,7 +155,51 @@ setup.template.settings: #number_of_routing_shards: 30 -#============================== Dashboards ===================================== +#============================== Template ===================================== + +# A template is used to set the mapping in Elasticsearch +# By default template loading is enabled and the template is loaded. +# These settings can be adjusted to load your own template or overwrite existing ones. + +# Set to false to disable template loading. +#setup.template.enabled: true + +# Template name. By default the template name is "apm-%{[beat.version]}" +# The template name and pattern has to be set in case the elasticsearch index pattern is modified. +#setup.template.name: "apm-%{[beat.version]}" + +# Template pattern. By default the template pattern is "apm-%{[beat.version]}-*" to apply to the default index settings. +# The first part is the version of the beat and then -* is used to match all daily indices. +# The template name and pattern has to be set in case the elasticsearch index pattern is modified. +#setup.template.pattern: "apm-%{[beat.version]}-*" + +# Path to fields.yml file to generate the template +#setup.template.fields: "${path.config}/fields.yml" + +# Overwrite existing template +#setup.template.overwrite: false + +# Elasticsearch template settings +#setup.template.settings: + + # A dictionary of settings to place into the settings.index dictionary + # of the Elasticsearch template. For more details, please check + # https://www.elastic.co/guide/en/elasticsearch/reference/current/mapping.html + #index: + #number_of_shards: 1 + #codec: best_compression + #number_of_routing_shards: 30 + + # A dictionary of settings for the _source field. For more details, please check + # https://www.elastic.co/guide/en/elasticsearch/reference/current/mapping-source-field.html + #_source: + #enabled: false + + +#============================== Deprecated: Dashboards ===================================== +# +# Deprecated: Loading dashboards from the APM Server into Kibana is deprecated from 6.4 on. +# We suggest to use the Kibana UI to load APM Server dashboards and index pattern instead. # # These settings control loading the sample dashboards to the Kibana index. Loading # the dashboards are disabled by default and can be enabled either by setting the @@ -197,51 +241,14 @@ setup.template.settings: #setup.dashboards.retry.maximum: 0 -#============================== Template ===================================== - -# A template is used to set the mapping in Elasticsearch -# By default template loading is enabled and the template is loaded. -# These settings can be adjusted to load your own template or overwrite existing ones. +#============================== Deprecated: Kibana ===================================== -# Set to false to disable template loading. -#setup.template.enabled: true - -# Template name. By default the template name is "apm-%{[beat.version]}" -# The template name and pattern has to be set in case the elasticsearch index pattern is modified. -#setup.template.name: "apm-%{[beat.version]}" - -# Template pattern. By default the template pattern is "apm-%{[beat.version]}-*" to apply to the default index settings. -# The first part is the version of the beat and then -* is used to match all daily indices. -# The template name and pattern has to be set in case the elasticsearch index pattern is modified. -#setup.template.pattern: "apm-%{[beat.version]}-*" - -# Path to fields.yml file to generate the template -#setup.template.fields: "${path.config}/fields.yml" - -# Overwrite existing template -#setup.template.overwrite: false - -# Elasticsearch template settings -#setup.template.settings: - - # A dictionary of settings to place into the settings.index dictionary - # of the Elasticsearch template. For more details, please check - # https://www.elastic.co/guide/en/elasticsearch/reference/current/mapping.html - #index: - #number_of_shards: 1 - #codec: best_compression - #number_of_routing_shards: 30 - - # A dictionary of settings for the _source field. For more details, please check - # https://www.elastic.co/guide/en/elasticsearch/reference/current/mapping-source-field.html - #_source: - #enabled: false - - -#============================== Kibana ===================================== +# Deprecated: Starting with APM Server version 6.4, loading dashboards and index pattern +# from the APM Server into Kibana is deprecated. +# We suggest to use the Kibana UI to load APM Server dashboards and index pattern instead. +# +# Setting up a Kibana endpoint is not necessary when loading the index pattern and dashboards via the UI. -# Starting with Beats version 6.0.0, the dashboards are loaded via the Kibana API. -# This requires a Kibana endpoint configuration. #setup.kibana: # Kibana Host diff --git a/apm-server.yml b/apm-server.yml index 4d22ea058c..1f059dcb23 100644 --- a/apm-server.yml +++ b/apm-server.yml @@ -155,7 +155,51 @@ setup.template.settings: #number_of_routing_shards: 30 -#============================== Dashboards ===================================== +#============================== Template ===================================== + +# A template is used to set the mapping in Elasticsearch +# By default template loading is enabled and the template is loaded. +# These settings can be adjusted to load your own template or overwrite existing ones. + +# Set to false to disable template loading. +#setup.template.enabled: true + +# Template name. By default the template name is "apm-%{[beat.version]}" +# The template name and pattern has to be set in case the elasticsearch index pattern is modified. +#setup.template.name: "apm-%{[beat.version]}" + +# Template pattern. By default the template pattern is "apm-%{[beat.version]}-*" to apply to the default index settings. +# The first part is the version of the beat and then -* is used to match all daily indices. +# The template name and pattern has to be set in case the elasticsearch index pattern is modified. +#setup.template.pattern: "apm-%{[beat.version]}-*" + +# Path to fields.yml file to generate the template +#setup.template.fields: "${path.config}/fields.yml" + +# Overwrite existing template +#setup.template.overwrite: false + +# Elasticsearch template settings +#setup.template.settings: + + # A dictionary of settings to place into the settings.index dictionary + # of the Elasticsearch template. For more details, please check + # https://www.elastic.co/guide/en/elasticsearch/reference/current/mapping.html + #index: + #number_of_shards: 1 + #codec: best_compression + #number_of_routing_shards: 30 + + # A dictionary of settings for the _source field. For more details, please check + # https://www.elastic.co/guide/en/elasticsearch/reference/current/mapping-source-field.html + #_source: + #enabled: false + + +#============================== Deprecated: Dashboards ===================================== +# +# Deprecated: Loading dashboards from the APM Server into Kibana is deprecated from 6.4 on. +# We suggest to use the Kibana UI to load APM Server dashboards and index pattern instead. # # These settings control loading the sample dashboards to the Kibana index. Loading # the dashboards are disabled by default and can be enabled either by setting the @@ -197,51 +241,14 @@ setup.template.settings: #setup.dashboards.retry.maximum: 0 -#============================== Template ===================================== - -# A template is used to set the mapping in Elasticsearch -# By default template loading is enabled and the template is loaded. -# These settings can be adjusted to load your own template or overwrite existing ones. +#============================== Deprecated: Kibana ===================================== -# Set to false to disable template loading. -#setup.template.enabled: true - -# Template name. By default the template name is "apm-%{[beat.version]}" -# The template name and pattern has to be set in case the elasticsearch index pattern is modified. -#setup.template.name: "apm-%{[beat.version]}" - -# Template pattern. By default the template pattern is "apm-%{[beat.version]}-*" to apply to the default index settings. -# The first part is the version of the beat and then -* is used to match all daily indices. -# The template name and pattern has to be set in case the elasticsearch index pattern is modified. -#setup.template.pattern: "apm-%{[beat.version]}-*" - -# Path to fields.yml file to generate the template -#setup.template.fields: "${path.config}/fields.yml" - -# Overwrite existing template -#setup.template.overwrite: false - -# Elasticsearch template settings -#setup.template.settings: - - # A dictionary of settings to place into the settings.index dictionary - # of the Elasticsearch template. For more details, please check - # https://www.elastic.co/guide/en/elasticsearch/reference/current/mapping.html - #index: - #number_of_shards: 1 - #codec: best_compression - #number_of_routing_shards: 30 - - # A dictionary of settings for the _source field. For more details, please check - # https://www.elastic.co/guide/en/elasticsearch/reference/current/mapping-source-field.html - #_source: - #enabled: false - - -#============================== Kibana ===================================== +# Deprecated: Starting with APM Server version 6.4, loading dashboards and index pattern +# from the APM Server into Kibana is deprecated. +# We suggest to use the Kibana UI to load APM Server dashboards and index pattern instead. +# +# Setting up a Kibana endpoint is not necessary when loading the index pattern and dashboards via the UI. -# Starting with Beats version 6.0.0, the dashboards are loaded via the Kibana API. -# This requires a Kibana endpoint configuration. #setup.kibana: # Kibana Host diff --git a/docs/configuring.asciidoc b/docs/configuring.asciidoc index 82aa3e63db..dbb7d61724 100644 --- a/docs/configuring.asciidoc +++ b/docs/configuring.asciidoc @@ -12,8 +12,8 @@ The following topics describe how to configure APM Server: * <> * <> * <> -* <> -* <> +* <> +* <> * <> * <> * <> diff --git a/docs/copied-from-beats/command-reference.asciidoc b/docs/copied-from-beats/command-reference.asciidoc index 346679fda6..83118b64bd 100644 --- a/docs/copied-from-beats/command-reference.asciidoc +++ b/docs/copied-from-beats/command-reference.asciidoc @@ -20,12 +20,23 @@ :modules-command-short-desc: Manages configured modules :run-command-short-desc: Runs {beatname_uc}. This command is used by default if you start {beatname_uc} without specifying a command +ifndef::deprecate_dashboard_loading[] + ifdef::has_ml_jobs[] :setup-command-short-desc: Sets up the initial environment, including the index template, Kibana dashboards (when available), and machine learning jobs (when available) endif::[] ifndef::has_ml_jobs[] -:setup-command-short-desc: Sets up the initial environment, including the index template, Kibana dashboards (when available) +:setup-command-short-desc: Sets up the initial environment, including the index template and Kibana dashboards (when available) +endif::[] + +endif::[] + +ifdef::deprecate_dashboard_loading[] + +:setup-command-short-desc: Sets up the initial environment, +including the ES index template and Kibana dashboards (deprecated). + endif::[] :test-command-short-desc: Tests the configuration @@ -39,9 +50,17 @@ endif::[] Command reference ++++ +ifndef::deprecate_dashboard_loading[] {beatname_uc} provides a command-line interface for starting {beatname_uc} and -performing common tasks, like testing configuration files and loading -dashboards. The command-line also supports <> +performing common tasks, like testing configuration files and loading dashboards. +endif::[] + +ifdef::deprecate_dashboard_loading[] +{beatname_uc} provides a command-line interface for starting {beatname_uc} and +performing common tasks, like testing configuration files and loading dashboards (deprecated). +endif::[] + +The command-line also supports <> for controlling global behaviors. ifeval::["{beatname_lc}"!="winlogbeat"] @@ -390,9 +409,24 @@ the end of the file is reached. By default harvesters are closed after endif::[] -*`--setup`*:: -Loads the sample Kibana dashboards. If you want to load the dashboards without -running {beatname_uc}, use the <> command instead. +ifndef::deprecate_dashboard_loading[] +*`--setup`*:: +endif::[] + +ifdef::deprecate_dashboard_loading[] +*`--setup (deprecated)`*:: +endif::[] + +ifdef::has_ml_jobs[] +Loads the initial setup, including Elasticsearch template, Kibana index pattern, +Kibana dashboards and Machine learning jobs. +endif::[] + +ifndef::has_ml_jobs[] +Loads the initial setup, including Elasticsearch template, Kibana index pattern and Kibana dashboards. +endif::[] + +If you want to use the command without running {beatname_uc}, use the <> command instead. ifeval::["{beatname_lc}"=="metricbeat"] @@ -434,10 +468,17 @@ Or: {setup-command-short-desc}. * The index template ensures that fields are mapped correctly in Elasticsearch. + * The Kibana dashboards make it easier for you to visualize {beatname_uc} data in Kibana. +ifdef::deprecate_dashboard_loading[] +(deprecated) +endif::[] + +ifdef::has_ml_jobs[] * The machine learning jobs contain the configuration information and metadata necessary to analyze data for anomalies. +endif::[] Use this command instead of `run --setup` when you want to set up the environment without actually running {beatname_uc} and ingesting data. @@ -452,18 +493,29 @@ environment without actually running {beatname_uc} and ingesting data. *FLAGS* +ifndef::deprecate_dashboard_loading[] *`--dashboards`*:: Sets up the Kibana dashboards only. This option loads the dashboards from the {beatname_uc} package. For more options, such as loading customized dashboards, see {beatsdevguide}/import-dashboards.html[Importing Existing Beat Dashboards] in the _Beats Developer Guide_. +endif::[] + +ifdef::deprecate_dashboard_loading[] +*`--dashboards` (deprecated)*:: +Sets up the Kibana dashboards only. +endif::[] *`-h, --help`*:: Shows help for the `setup` command. +ifdef::has_ml_jobs[] + *`--machine-learning`*:: Sets up machine learning job configurations only. +endif::[] + ifeval::["{beatname_lc}"=="filebeat"] *`--modules MODULE_LIST`*:: diff --git a/docs/copied-from-beats/dashboardsconfig.asciidoc b/docs/copied-from-beats/dashboardsconfig.asciidoc index fbc9f1a202..cb0313772e 100644 --- a/docs/copied-from-beats/dashboardsconfig.asciidoc +++ b/docs/copied-from-beats/dashboardsconfig.asciidoc @@ -10,7 +10,7 @@ ////////////////////////////////////////////////////////////////////////// [[configuration-dashboards]] -== Load the Kibana dashboards +== Load the Kibana dashboards (deprecated) {beatname_uc} comes packaged with example Kibana dashboards, visualizations, and searches for visualizing {beatname_uc} data in Kibana. diff --git a/docs/copied-from-beats/outputconfig.asciidoc b/docs/copied-from-beats/outputconfig.asciidoc index 8eeb556625..7cfcdd17ec 100644 --- a/docs/copied-from-beats/outputconfig.asciidoc +++ b/docs/copied-from-beats/outputconfig.asciidoc @@ -216,10 +216,21 @@ The index name to write events to. The default is +"{beatname_lc}-%\{[beat.version]\}-%\{+yyyy.MM.dd\}"+ (for example, +"{beatname_lc}-{version}-2017.04.26"+). If you change this setting, you also need to configure the `setup.template.name` and `setup.template.pattern` options -(see <>). If you are using the pre-built Kibana -dashboards, you also need to set the `setup.dashboards.index` option (see -<>). +(see <>). +ifndef::deprecate_dashboard_loading[] + +If you are using the pre-built Kibana dashboards, +you also need to set the `setup.dashboards.index` option (see <>). + +endif::[] + +ifdef::deprecate_dashboard_loading[] + +If you are using the pre-built Kibana dashboards, +you also need to set the index pattern properly when loading the dashboards via the Kibana UI. + +endif::[] ===== `indices` diff --git a/docs/copied-from-beats/shared-kibana-config.asciidoc b/docs/copied-from-beats/shared-kibana-config.asciidoc index d373a5bc0b..b43477aa14 100644 --- a/docs/copied-from-beats/shared-kibana-config.asciidoc +++ b/docs/copied-from-beats/shared-kibana-config.asciidoc @@ -10,7 +10,7 @@ ////////////////////////////////////////////////////////////////////////// [[setup-kibana-endpoint]] -== Set up the Kibana endpoint +== Set up the Kibana endpoint (deprecated) ifeval::["{beatname_lc}" == "apm-server"] The Kibana dashboards are loaded into Kibana via the Kibana API. diff --git a/docs/copied-from-beats/shared-ssl-config.asciidoc b/docs/copied-from-beats/shared-ssl-config.asciidoc index 6034a92482..8f6c24d862 100644 --- a/docs/copied-from-beats/shared-ssl-config.asciidoc +++ b/docs/copied-from-beats/shared-ssl-config.asciidoc @@ -5,6 +5,7 @@ You can specify SSL options when you configure: * <> that support SSL * the <> + ifeval::["{beatname_lc}"=="heartbeat"] * <> that support SSL endif::[] @@ -23,6 +24,7 @@ ifndef::only-elasticsearch[] Also see <>. endif::[] + Example Kibana endpoint config with SSL enabled: [source,yaml] diff --git a/docs/copied-from-beats/shared-template-load.asciidoc b/docs/copied-from-beats/shared-template-load.asciidoc index e3bc17cea9..3aef5410f5 100644 --- a/docs/copied-from-beats/shared-template-load.asciidoc +++ b/docs/copied-from-beats/shared-template-load.asciidoc @@ -94,6 +94,8 @@ that you specify should include the root name of the index plus version and date information. You also need to configure the `setup.template.name` and `setup.template.pattern` options to match the new name. For example: + +ifndef::deprecate_dashboard_loading[] + ["source","sh",subs="attributes,callouts"] ----- output.elasticsearch.index: "customname-%{[beat.version]}-%{+yyyy.MM.dd}" @@ -101,11 +103,28 @@ setup.template.name: "customname" setup.template.pattern: "customname-*" setup.dashboards.index: "customname-*" <1> ----- + <1> If you plan to <>, also set this option to overwrite the index name defined in the dashboards and index pattern. +endif::[] + +ifdef::deprecate_dashboard_loading[] + +["source","sh",subs="attributes,callouts"] +----- +output.elasticsearch.index: "customname-%{[beat.version]}-%{+yyyy.MM.dd}" +setup.template.name: "customname" +setup.template.pattern: "customname-*" +----- ++ +Also ensure to change the index name accordingly in the Kibana dashboards, +when loading via the Kibana UI. + +endif::[] + See <> for the full list of configuration options. diff --git a/docs/dashboards.asciidoc b/docs/dashboards.asciidoc index cf10ae8f51..0738b854bf 100644 --- a/docs/dashboards.asciidoc +++ b/docs/dashboards.asciidoc @@ -1,5 +1,53 @@ [[load-kibana-dashboards]] === Dashboards +From APM Server and Kibana 6.4 on you can load dashboards directly via the Kibana UI. -include::./copied-from-beats/dashboards.asciidoc[] \ No newline at end of file +NOTE: Loading index pattern and dashboards through the APM Server is deprecated. + It is recommended to use the Kibana UI instead. + +==== Setup via APM Server (deprecated) +Loading via APM Server requires a <>. +If you are accessing a secured Kibana instance, make sure you've configured credentials. + +You have to either <> in the ++{beatname_lc}.yml+ config file, +or run the appropriate `setup` command for your system: + +*deb and rpm:* + +["source","sh",subs="attributes"] +---------------------------------------------------------------------- +{beatname_lc} setup --dashboards +---------------------------------------------------------------------- + + +*mac:* + +["source","sh",subs="attributes"] +---------------------------------------------------------------------- +./{beatname_lc} setup --dashboards +---------------------------------------------------------------------- + + +*docker:* + +["source","sh",subs="attributes"] +---------------------------------------------------------------------- +docker run {dockerimage} setup --dashboards +---------------------------------------------------------------------- + +*win:* + +endif::allplatforms[] + +Open a PowerShell prompt as an Administrator (right-click the PowerShell icon +and select *Run As Administrator*). + +From the PowerShell prompt, change to the directory where you installed {beatname_uc}, +and run: + +["source","sh",subs="attributes"] +---------------------------------------------------------------------- +PS > .{backslash}{beatname_lc}.exe setup --dashboards +---------------------------------------------------------------------- diff --git a/docs/guide/index.asciidoc b/docs/guide/index.asciidoc index 02894d23c6..b80d0881ce 100644 --- a/docs/guide/index.asciidoc +++ b/docs/guide/index.asciidoc @@ -58,7 +58,7 @@ APM Server creates documents from the data received from agents and stores them To visualize the data after it's sent to Elasticsearch, you can use the the dedicated APM UI bundled in X-Pack, -or the pre-built open source Kibana dashboards that come with APM Server. +or the pre-built open source Kibana dashboards that can be loaded directly in the Kibana UI. We designed Elastic APM to run on anything from a regular laptop to thousands of machines, and it's easy to get started. @@ -148,16 +148,8 @@ You can also configure APM Server to listen on a Unix domain socket. [[kibana-dashboards]] [float] ==== Install the Kibana dashboards -APM Server comes with predefined Kibana dashboards and index templates for APM data. -To install those run the following command: - -[source,bash] ----------------------------------- -./apm-server setup ----------------------------------- - -NOTE: Due to a bug in Kibana 6.0.0.-rc2 the dashboards don't work in Kibana 6.0.0-rc2. +From APM Server and Kibana 6.4 on you can load dashboards directly via the Kibana UI. See an example screenshot of a Kibana dashboard: diff --git a/docs/index.asciidoc b/docs/index.asciidoc index 22d6b39c16..6808b4d3f9 100644 --- a/docs/index.asciidoc +++ b/docs/index.asciidoc @@ -17,6 +17,7 @@ include::{asciidoc-dir}/../../shared/attributes.asciidoc[] :logstashdoc: https://www.elastic.co/guide/en/logstash/{doc-branch} :elasticsearch: https://www.elastic.co/guide/en/elasticsearch/reference/{doc-branch} :securitydoc: https://www.elastic.co/guide/en/elastic-stack-overview/{doc-branch} +:deprecate_dashboard_loading: true ifdef::env-github[] NOTE: For the best reading experience, diff --git a/docs/setting-up-and-running.asciidoc b/docs/setting-up-and-running.asciidoc index c83a91883c..994d25b2e8 100644 --- a/docs/setting-up-and-running.asciidoc +++ b/docs/setting-up-and-running.asciidoc @@ -57,24 +57,6 @@ output.elasticsearch: password: "elastic" ---- -If you plan to use the sample Kibana dashboards provided with {beatname_uc}, -configure the Kibana endpoint: - -[source,yaml] ----------------------------------------------------------------------- -setup.kibana: - host: "localhost:5601" ----------------------------------------------------------------------- - --- -Where `host` is the hostname and port of the machine where Kibana is running, -for example, `localhost:5601`. - -NOTE: If you specify a path after the port number, you need to include -the scheme and port: `http://localhost:5601/path`. - --- - See <> for more configuration options. From 9daf5943c608058a6729de0ea63a808ce80a63ca Mon Sep 17 00:00:00 2001 From: simitt Date: Mon, 23 Jul 2018 09:38:09 +0200 Subject: [PATCH 5/6] update beats docs. --- .../command-reference.asciidoc | 28 +++++++++---------- .../dashboardsconfig.asciidoc | 6 ++++ docs/copied-from-beats/outputconfig.asciidoc | 10 +++---- .../shared-kibana-config.asciidoc | 6 ++++ .../shared-ssl-config.asciidoc | 2 -- .../shared-template-load.asciidoc | 4 +-- 6 files changed, 33 insertions(+), 23 deletions(-) diff --git a/docs/copied-from-beats/command-reference.asciidoc b/docs/copied-from-beats/command-reference.asciidoc index 83118b64bd..afe04d98f2 100644 --- a/docs/copied-from-beats/command-reference.asciidoc +++ b/docs/copied-from-beats/command-reference.asciidoc @@ -20,7 +20,7 @@ :modules-command-short-desc: Manages configured modules :run-command-short-desc: Runs {beatname_uc}. This command is used by default if you start {beatname_uc} without specifying a command -ifndef::deprecate_dashboard_loading[] +ifndef::deprecate_dashboard_loading[] ifdef::has_ml_jobs[] :setup-command-short-desc: Sets up the initial environment, including the index template, Kibana dashboards (when available), and machine learning jobs (when available) @@ -32,9 +32,9 @@ endif::[] endif::[] -ifdef::deprecate_dashboard_loading[] +ifdef::deprecate_dashboard_loading[] -:setup-command-short-desc: Sets up the initial environment, +:setup-command-short-desc: Sets up the initial environment, including the ES index template and Kibana dashboards (deprecated). endif::[] @@ -50,12 +50,12 @@ endif::[] Command reference ++++ -ifndef::deprecate_dashboard_loading[] +ifndef::deprecate_dashboard_loading[] {beatname_uc} provides a command-line interface for starting {beatname_uc} and -performing common tasks, like testing configuration files and loading dashboards. +performing common tasks, like testing configuration files and loading dashboards. endif::[] -ifdef::deprecate_dashboard_loading[] +ifdef::deprecate_dashboard_loading[] {beatname_uc} provides a command-line interface for starting {beatname_uc} and performing common tasks, like testing configuration files and loading dashboards (deprecated). endif::[] @@ -409,16 +409,16 @@ the end of the file is reached. By default harvesters are closed after endif::[] -ifndef::deprecate_dashboard_loading[] -*`--setup`*:: +ifndef::deprecate_dashboard_loading[] +*`--setup`*:: endif::[] -ifdef::deprecate_dashboard_loading[] -*`--setup (deprecated)`*:: +ifdef::deprecate_dashboard_loading[] +*`--setup (deprecated)`*:: endif::[] ifdef::has_ml_jobs[] -Loads the initial setup, including Elasticsearch template, Kibana index pattern, +Loads the initial setup, including Elasticsearch template, Kibana index pattern, Kibana dashboards and Machine learning jobs. endif::[] @@ -471,7 +471,7 @@ Or: * The Kibana dashboards make it easier for you to visualize {beatname_uc} data in Kibana. -ifdef::deprecate_dashboard_loading[] +ifdef::deprecate_dashboard_loading[] (deprecated) endif::[] @@ -493,7 +493,7 @@ environment without actually running {beatname_uc} and ingesting data. *FLAGS* -ifndef::deprecate_dashboard_loading[] +ifndef::deprecate_dashboard_loading[] *`--dashboards`*:: Sets up the Kibana dashboards only. This option loads the dashboards from the {beatname_uc} package. For more options, such as loading customized dashboards, @@ -501,7 +501,7 @@ see {beatsdevguide}/import-dashboards.html[Importing Existing Beat Dashboards] in the _Beats Developer Guide_. endif::[] -ifdef::deprecate_dashboard_loading[] +ifdef::deprecate_dashboard_loading[] *`--dashboards` (deprecated)*:: Sets up the Kibana dashboards only. endif::[] diff --git a/docs/copied-from-beats/dashboardsconfig.asciidoc b/docs/copied-from-beats/dashboardsconfig.asciidoc index cb0313772e..7050593613 100644 --- a/docs/copied-from-beats/dashboardsconfig.asciidoc +++ b/docs/copied-from-beats/dashboardsconfig.asciidoc @@ -10,7 +10,13 @@ ////////////////////////////////////////////////////////////////////////// [[configuration-dashboards]] +ifndef::deprecate_dashboard_loading[] +== Load the Kibana dashboards +endif::[] + +ifdef::deprecate_dashboard_loading[] == Load the Kibana dashboards (deprecated) +endif::[] {beatname_uc} comes packaged with example Kibana dashboards, visualizations, and searches for visualizing {beatname_uc} data in Kibana. diff --git a/docs/copied-from-beats/outputconfig.asciidoc b/docs/copied-from-beats/outputconfig.asciidoc index 7cfcdd17ec..2cc1917fe3 100644 --- a/docs/copied-from-beats/outputconfig.asciidoc +++ b/docs/copied-from-beats/outputconfig.asciidoc @@ -216,18 +216,18 @@ The index name to write events to. The default is +"{beatname_lc}-%\{[beat.version]\}-%\{+yyyy.MM.dd\}"+ (for example, +"{beatname_lc}-{version}-2017.04.26"+). If you change this setting, you also need to configure the `setup.template.name` and `setup.template.pattern` options -(see <>). +(see <>). -ifndef::deprecate_dashboard_loading[] +ifndef::deprecate_dashboard_loading[] -If you are using the pre-built Kibana dashboards, +If you are using the pre-built Kibana dashboards, you also need to set the `setup.dashboards.index` option (see <>). endif::[] -ifdef::deprecate_dashboard_loading[] +ifdef::deprecate_dashboard_loading[] -If you are using the pre-built Kibana dashboards, +If you are using the pre-built Kibana dashboards, you also need to set the index pattern properly when loading the dashboards via the Kibana UI. endif::[] diff --git a/docs/copied-from-beats/shared-kibana-config.asciidoc b/docs/copied-from-beats/shared-kibana-config.asciidoc index b43477aa14..9e5ae2b9ba 100644 --- a/docs/copied-from-beats/shared-kibana-config.asciidoc +++ b/docs/copied-from-beats/shared-kibana-config.asciidoc @@ -10,7 +10,13 @@ ////////////////////////////////////////////////////////////////////////// [[setup-kibana-endpoint]] +ifndef::deprecate_dashboard_loading[] +== Set up the Kibana endpoint +endif::[] +ifdef::deprecate_dashboard_loading[] == Set up the Kibana endpoint (deprecated) +endif::[] + ifeval::["{beatname_lc}" == "apm-server"] The Kibana dashboards are loaded into Kibana via the Kibana API. diff --git a/docs/copied-from-beats/shared-ssl-config.asciidoc b/docs/copied-from-beats/shared-ssl-config.asciidoc index 8f6c24d862..6034a92482 100644 --- a/docs/copied-from-beats/shared-ssl-config.asciidoc +++ b/docs/copied-from-beats/shared-ssl-config.asciidoc @@ -5,7 +5,6 @@ You can specify SSL options when you configure: * <> that support SSL * the <> - ifeval::["{beatname_lc}"=="heartbeat"] * <> that support SSL endif::[] @@ -24,7 +23,6 @@ ifndef::only-elasticsearch[] Also see <>. endif::[] - Example Kibana endpoint config with SSL enabled: [source,yaml] diff --git a/docs/copied-from-beats/shared-template-load.asciidoc b/docs/copied-from-beats/shared-template-load.asciidoc index 3aef5410f5..6f4f1c7da8 100644 --- a/docs/copied-from-beats/shared-template-load.asciidoc +++ b/docs/copied-from-beats/shared-template-load.asciidoc @@ -94,7 +94,7 @@ that you specify should include the root name of the index plus version and date information. You also need to configure the `setup.template.name` and `setup.template.pattern` options to match the new name. For example: + -ifndef::deprecate_dashboard_loading[] +ifndef::deprecate_dashboard_loading[] ["source","sh",subs="attributes,callouts"] ----- @@ -111,7 +111,7 @@ pattern. endif::[] -ifdef::deprecate_dashboard_loading[] +ifdef::deprecate_dashboard_loading[] ["source","sh",subs="attributes,callouts"] ----- From 6bd8383818251cb68c63eafaab8150eb148a7faa Mon Sep 17 00:00:00 2001 From: simitt Date: Mon, 23 Jul 2018 14:36:19 +0200 Subject: [PATCH 6/6] Align with beats, use `deprecated`. --- docs/configuring.asciidoc | 4 ++-- .../command-reference.asciidoc | 23 ++++++++----------- .../dashboardsconfig.asciidoc | 7 +++--- docs/copied-from-beats/outputconfig.asciidoc | 7 +----- .../shared-kibana-config.asciidoc | 7 +++--- docs/dashboards.asciidoc | 6 ++--- docs/index.asciidoc | 2 +- 7 files changed, 22 insertions(+), 34 deletions(-) diff --git a/docs/configuring.asciidoc b/docs/configuring.asciidoc index dbb7d61724..82aa3e63db 100644 --- a/docs/configuring.asciidoc +++ b/docs/configuring.asciidoc @@ -12,8 +12,8 @@ The following topics describe how to configure APM Server: * <> * <> * <> -* <> -* <> +* <> +* <> * <> * <> * <> diff --git a/docs/copied-from-beats/command-reference.asciidoc b/docs/copied-from-beats/command-reference.asciidoc index afe04d98f2..e2f37f911a 100644 --- a/docs/copied-from-beats/command-reference.asciidoc +++ b/docs/copied-from-beats/command-reference.asciidoc @@ -34,8 +34,7 @@ endif::[] ifdef::deprecate_dashboard_loading[] -:setup-command-short-desc: Sets up the initial environment, -including the ES index template and Kibana dashboards (deprecated). +:setup-command-short-desc: Sets up the initial environment, including the ES index template and Kibana dashboards (deprecated). endif::[] @@ -409,25 +408,21 @@ the end of the file is reached. By default harvesters are closed after endif::[] -ifndef::deprecate_dashboard_loading[] *`--setup`*:: -endif::[] - ifdef::deprecate_dashboard_loading[] -*`--setup (deprecated)`*:: +deprecated[{deprecate_dashboard_loading}] endif::[] - ++ ifdef::has_ml_jobs[] Loads the initial setup, including Elasticsearch template, Kibana index pattern, Kibana dashboards and Machine learning jobs. endif::[] - ifndef::has_ml_jobs[] Loads the initial setup, including Elasticsearch template, Kibana index pattern and Kibana dashboards. endif::[] - If you want to use the command without running {beatname_uc}, use the <> command instead. + ifeval::["{beatname_lc}"=="metricbeat"] *`--system.hostfs MOUNT_POINT`*:: @@ -465,15 +460,12 @@ Or: [[setup-command]] ==== `setup` command -{setup-command-short-desc}. +{setup-command-short-desc} * The index template ensures that fields are mapped correctly in Elasticsearch. * The Kibana dashboards make it easier for you to visualize {beatname_uc} data in Kibana. -ifdef::deprecate_dashboard_loading[] -(deprecated) -endif::[] ifdef::has_ml_jobs[] * The machine learning jobs contain the configuration information and metadata @@ -502,7 +494,10 @@ in the _Beats Developer Guide_. endif::[] ifdef::deprecate_dashboard_loading[] -*`--dashboards` (deprecated)*:: +*`--dashboards`*:: + +deprecated[{deprecate_dashboard_loading}] ++ Sets up the Kibana dashboards only. endif::[] diff --git a/docs/copied-from-beats/dashboardsconfig.asciidoc b/docs/copied-from-beats/dashboardsconfig.asciidoc index 7050593613..83099f84d1 100644 --- a/docs/copied-from-beats/dashboardsconfig.asciidoc +++ b/docs/copied-from-beats/dashboardsconfig.asciidoc @@ -10,12 +10,11 @@ ////////////////////////////////////////////////////////////////////////// [[configuration-dashboards]] -ifndef::deprecate_dashboard_loading[] == Load the Kibana dashboards -endif::[] - ifdef::deprecate_dashboard_loading[] -== Load the Kibana dashboards (deprecated) + +deprecated[{deprecate_dashboard_loading}] + endif::[] {beatname_uc} comes packaged with example Kibana dashboards, visualizations, diff --git a/docs/copied-from-beats/outputconfig.asciidoc b/docs/copied-from-beats/outputconfig.asciidoc index 2cc1917fe3..022b31d9c7 100644 --- a/docs/copied-from-beats/outputconfig.asciidoc +++ b/docs/copied-from-beats/outputconfig.asciidoc @@ -218,17 +218,12 @@ The index name to write events to. The default is need to configure the `setup.template.name` and `setup.template.pattern` options (see <>). -ifndef::deprecate_dashboard_loading[] - If you are using the pre-built Kibana dashboards, you also need to set the `setup.dashboards.index` option (see <>). -endif::[] - ifdef::deprecate_dashboard_loading[] -If you are using the pre-built Kibana dashboards, -you also need to set the index pattern properly when loading the dashboards via the Kibana UI. +deprecated[{deprecate_dashboard_loading}] endif::[] diff --git a/docs/copied-from-beats/shared-kibana-config.asciidoc b/docs/copied-from-beats/shared-kibana-config.asciidoc index 9e5ae2b9ba..51ba2f0c3e 100644 --- a/docs/copied-from-beats/shared-kibana-config.asciidoc +++ b/docs/copied-from-beats/shared-kibana-config.asciidoc @@ -10,13 +10,12 @@ ////////////////////////////////////////////////////////////////////////// [[setup-kibana-endpoint]] -ifndef::deprecate_dashboard_loading[] == Set up the Kibana endpoint -endif::[] ifdef::deprecate_dashboard_loading[] -== Set up the Kibana endpoint (deprecated) -endif::[] +deprecated[{deprecate_dashboard_loading}] + +endif::[] ifeval::["{beatname_lc}" == "apm-server"] The Kibana dashboards are loaded into Kibana via the Kibana API. diff --git a/docs/dashboards.asciidoc b/docs/dashboards.asciidoc index 0738b854bf..c03ebd8f05 100644 --- a/docs/dashboards.asciidoc +++ b/docs/dashboards.asciidoc @@ -3,10 +3,10 @@ From APM Server and Kibana 6.4 on you can load dashboards directly via the Kibana UI. -NOTE: Loading index pattern and dashboards through the APM Server is deprecated. - It is recommended to use the Kibana UI instead. +==== Setup via APM Server + +deprecated[{deprecate_dashboard_loading}] -==== Setup via APM Server (deprecated) Loading via APM Server requires a <>. If you are accessing a secured Kibana instance, make sure you've configured credentials. diff --git a/docs/index.asciidoc b/docs/index.asciidoc index 6808b4d3f9..0fa53a1d3a 100644 --- a/docs/index.asciidoc +++ b/docs/index.asciidoc @@ -17,7 +17,7 @@ include::{asciidoc-dir}/../../shared/attributes.asciidoc[] :logstashdoc: https://www.elastic.co/guide/en/logstash/{doc-branch} :elasticsearch: https://www.elastic.co/guide/en/elasticsearch/reference/{doc-branch} :securitydoc: https://www.elastic.co/guide/en/elastic-stack-overview/{doc-branch} -:deprecate_dashboard_loading: true +:deprecate_dashboard_loading: 6.4.0 ifdef::env-github[] NOTE: For the best reading experience,