From 16608945284c27d31b0e680f53a3bfd8aa11b6fd Mon Sep 17 00:00:00 2001 From: Khushi Jain Date: Mon, 2 Dec 2024 19:14:18 +0530 Subject: [PATCH 01/48] [FlakyTest] TestFileWatcher/does_not_emit_events_for_empty_files/emits_a_create_event_once_something_is_written_to_the_empty_file (#41848) * Fixes flaky test TestFileWatcher --- filebeat/input/filestream/fswatch_test.go | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/filebeat/input/filestream/fswatch_test.go b/filebeat/input/filestream/fswatch_test.go index 528caec79de3..9fae0481ca6a 100644 --- a/filebeat/input/filestream/fswatch_test.go +++ b/filebeat/input/filestream/fswatch_test.go @@ -36,7 +36,6 @@ import ( ) func TestFileWatcher(t *testing.T) { - t.Skip("Flaky test: https://github.com/elastic/beats/issues/41209") dir := t.TempDir() paths := []string{filepath.Join(dir, "*.log")} cfgStr := ` @@ -261,10 +260,10 @@ scanner: paths := []string{filepath.Join(dir, "*.log")} cfgStr := ` scanner: - check_interval: 10ms + check_interval: 50ms ` - ctx, cancel := context.WithTimeout(context.Background(), 100*time.Millisecond) + ctx, cancel := context.WithTimeout(context.Background(), 1000*time.Millisecond) defer cancel() logp.DevelopmentSetup(logp.ToObserverOutput()) From 3144d384801a876330d0394c0d4c39e8688a0d61 Mon Sep 17 00:00:00 2001 From: Ishleen Kaur <102962586+ishleenk17@users.noreply.github.com> Date: Mon, 2 Dec 2024 19:48:32 +0530 Subject: [PATCH 02/48] Support `location_label` config in GCP Metrics Metricset (#41626) * Support of servicelabel config * Update the label * update location_label * Add metricbeat and gcp.yml.disabled * Update changelog * update gcp asciidoc * adress review comments --- CHANGELOG.next.asciidoc | 1 + metricbeat/docs/modules/gcp.asciidoc | 1 + x-pack/metricbeat/metricbeat.reference.yml | 1 + x-pack/metricbeat/module/gcp/_meta/config.yml | 1 + .../module/gcp/metrics/_meta/docs.asciidoc | 27 +++++++++++++++++++ .../module/gcp/metrics/metrics_requester.go | 12 ++++++++- .../gcp/metrics/metrics_requester_test.go | 7 +++++ .../module/gcp/metrics/metricset.go | 1 + x-pack/metricbeat/modules.d/gcp.yml.disabled | 1 + 9 files changed, 51 insertions(+), 1 deletion(-) diff --git a/CHANGELOG.next.asciidoc b/CHANGELOG.next.asciidoc index c1e655060b4e..b4e618e2da4c 100644 --- a/CHANGELOG.next.asciidoc +++ b/CHANGELOG.next.asciidoc @@ -397,6 +397,7 @@ https://github.com/elastic/beats/compare/v8.8.1\...main[Check the HEAD diff] - Bump aerospike-client-go to version v7.7.1 and add support for basic auth in Aerospike module {pull}41233[41233] - Only watch metadata for ReplicaSets in metricbeat k8s module {pull}41289[41289] - Add support for region/zone for Vertex AI service in GCP module {pull}41551[41551] +- Add support for location label as an optional configuration parameter in GCP metrics metricset. {issue}41550[41550] {pull}41626[41626] *Metricbeat* diff --git a/metricbeat/docs/modules/gcp.asciidoc b/metricbeat/docs/modules/gcp.asciidoc index 00c1536e5c04..11f3b14eaff0 100644 --- a/metricbeat/docs/modules/gcp.asciidoc +++ b/metricbeat/docs/modules/gcp.asciidoc @@ -346,6 +346,7 @@ metricbeat.modules: credentials_file_path: "your JSON credentials file path" exclude_labels: false period: 1m + location_label: "resource.labels.zone" metrics: - aligner: ALIGN_NONE service: compute diff --git a/x-pack/metricbeat/metricbeat.reference.yml b/x-pack/metricbeat/metricbeat.reference.yml index 7a32f16c19c8..f7f048da84bd 100644 --- a/x-pack/metricbeat/metricbeat.reference.yml +++ b/x-pack/metricbeat/metricbeat.reference.yml @@ -618,6 +618,7 @@ metricbeat.modules: credentials_file_path: "your JSON credentials file path" exclude_labels: false period: 1m + location_label: "resource.labels.zone" metrics: - aligner: ALIGN_NONE service: compute diff --git a/x-pack/metricbeat/module/gcp/_meta/config.yml b/x-pack/metricbeat/module/gcp/_meta/config.yml index ad0c7da852fa..55001654db98 100644 --- a/x-pack/metricbeat/module/gcp/_meta/config.yml +++ b/x-pack/metricbeat/module/gcp/_meta/config.yml @@ -34,6 +34,7 @@ credentials_file_path: "your JSON credentials file path" exclude_labels: false period: 1m + location_label: "resource.labels.zone" metrics: - aligner: ALIGN_NONE service: compute diff --git a/x-pack/metricbeat/module/gcp/metrics/_meta/docs.asciidoc b/x-pack/metricbeat/module/gcp/metrics/_meta/docs.asciidoc index 642df10f4962..40dc27e80e8f 100644 --- a/x-pack/metricbeat/module/gcp/metrics/_meta/docs.asciidoc +++ b/x-pack/metricbeat/module/gcp/metrics/_meta/docs.asciidoc @@ -45,6 +45,8 @@ services under "Google Cloud metrics", but does not work for other services (`kubernetes` aka GKE for example). This option allow to override the default and specify an arbitrary metric prefix. +* *location_label*: Use this option to specify the resource label that identifies the location (such as zone or region) for a Google Cloud service when filtering metrics. For example, labels like `resource.label.location` or `resource.label.zone` are used by Google Cloud to represent the region or zone of a resource. This is an optional configuration for the user. + [float] === Example Configuration * `metrics` metricset is enabled to collect metrics from all zones under @@ -134,3 +136,28 @@ metric prefix, as for GKE metrics the required prefix is `kubernetes.io/` metric_types: - "container/cpu/core_usage_time" ---- + +* `metrics` metricset is enabled to collect metrics from region +`us-east4` in `elastic-observability` project. The metric, number of replicas of the prediction model is +collected from a new GCP service `aiplatform`. Since its a new service which is not supported by +default in this metricset, the user provides the servicelabel (resource.label.location), for which +user wants to filter the incoming data + ++ +[source,yaml] +---- +- module: gcp + metricsets: + - metrics + project_id: "elastic-observability" + credentials_json: "your JSON credentials" + exclude_labels: false + period: 1m + location_label: "resource.label.location" # This is an optional configuration + regions: + - us-east4 + metrics: + - service: aiplatform + metric_types: + - "prediction/online/replicas" +---- \ No newline at end of file diff --git a/x-pack/metricbeat/module/gcp/metrics/metrics_requester.go b/x-pack/metricbeat/module/gcp/metrics/metrics_requester.go index ad0632e6c852..915ff63190f0 100644 --- a/x-pack/metricbeat/module/gcp/metrics/metrics_requester.go +++ b/x-pack/metricbeat/module/gcp/metrics/metrics_requester.go @@ -251,7 +251,7 @@ func (r *metricsRequester) getFilterForMetric(serviceName, m string) string { // NOTE: some GCP services are global, not regional or zonal. To these services we don't need // to apply any additional filters. if locationsConfigsAvailable && !isAGlobalService(serviceName) { - serviceLabel := getServiceLabelFor(serviceName) + serviceLabel := r.getServiceLabel(serviceName) f = r.buildLocationFilter(serviceLabel, f) } @@ -261,6 +261,16 @@ func (r *metricsRequester) getFilterForMetric(serviceName, m string) string { return f } +// getServiceLabel determines the service label to be used for the given service name. If a custom +// location label is configured, it will be used. Otherwise, the default service label for the +// given service name will be returned. +func (r *metricsRequester) getServiceLabel(serviceName string) string { + if r.config.LocationLabel != "" { + return r.config.LocationLabel + } + return getServiceLabelFor(serviceName) +} + // Returns a GCP TimeInterval based on the ingestDelay and samplePeriod from ListMetricDescriptor func getTimeIntervalAligner(ingestDelay time.Duration, samplePeriod time.Duration, collectionPeriod *durationpb.Duration, inputAligner string) (*monitoringpb.TimeInterval, string) { var startTime, endTime, currentTime time.Time diff --git a/x-pack/metricbeat/module/gcp/metrics/metrics_requester_test.go b/x-pack/metricbeat/module/gcp/metrics/metrics_requester_test.go index 9fb044e39e5f..20f8a5d9e366 100644 --- a/x-pack/metricbeat/module/gcp/metrics/metrics_requester_test.go +++ b/x-pack/metricbeat/module/gcp/metrics/metrics_requester_test.go @@ -128,6 +128,13 @@ func TestGetFilterForMetric(t *testing.T) { metricsRequester{config: config{Region: "foobar", Regions: []string{"foo", "bar"}}, logger: logger}, "metric.type=\"dummy\" AND resource.labels.zone = starts_with(\"foobar\")", }, + { + "aiplatform service with configured region and zone", + "aiplatform", + "", + metricsRequester{config: config{Region: "foo", Zone: "bar", LocationLabel: "resource.label.location"}, logger: logger}, + "metric.type=\"dummy\" AND resource.label.location = starts_with(\"foo\")", + }, } for _, c := range cases { diff --git a/x-pack/metricbeat/module/gcp/metrics/metricset.go b/x-pack/metricbeat/module/gcp/metrics/metricset.go index f5b15d68fb3e..660f1936f893 100644 --- a/x-pack/metricbeat/module/gcp/metrics/metricset.go +++ b/x-pack/metricbeat/module/gcp/metrics/metricset.go @@ -103,6 +103,7 @@ type config struct { Zone string `config:"zone"` Region string `config:"region"` Regions []string `config:"regions"` + LocationLabel string `config:"location_label"` ProjectID string `config:"project_id" validate:"required"` ExcludeLabels bool `config:"exclude_labels"` CredentialsFilePath string `config:"credentials_file_path"` diff --git a/x-pack/metricbeat/modules.d/gcp.yml.disabled b/x-pack/metricbeat/modules.d/gcp.yml.disabled index c8cddd198ce3..6bb0c9bad2a8 100644 --- a/x-pack/metricbeat/modules.d/gcp.yml.disabled +++ b/x-pack/metricbeat/modules.d/gcp.yml.disabled @@ -37,6 +37,7 @@ credentials_file_path: "your JSON credentials file path" exclude_labels: false period: 1m + location_label: "resource.labels.zone" metrics: - aligner: ALIGN_NONE service: compute From 0eb63c16f21a5120b380c9ab51d4d3ba7a78d5da Mon Sep 17 00:00:00 2001 From: Lee E Hinman <57081003+leehinman@users.noreply.github.com> Date: Mon, 2 Dec 2024 08:46:30 -0600 Subject: [PATCH 03/48] move metricbeat command definition out of init (#41816) --- metricbeat/cmd/root.go | 9 +-------- metricbeat/main.go | 2 +- metricbeat/main_test.go | 20 +++++++++++++------ x-pack/agentbeat/main.go | 2 +- .../tests/mbtest/metricbeat_v2_test.go | 7 ++++--- .../mbtest/system/process_integration_test.go | 5 +++-- x-pack/metricbeat/cmd/root.go | 14 ++++++------- x-pack/metricbeat/main.go | 2 +- x-pack/metricbeat/main_test.go | 20 +++++++++++++------ 9 files changed, 45 insertions(+), 36 deletions(-) diff --git a/metricbeat/cmd/root.go b/metricbeat/cmd/root.go index 497b71bed8ad..872f05b8b356 100644 --- a/metricbeat/cmd/root.go +++ b/metricbeat/cmd/root.go @@ -43,9 +43,6 @@ const ( Name = "metricbeat" ) -// RootCmd to handle beats cli -var RootCmd *cmd.BeatsRootCmd - // withECSVersion is a modifier that adds ecs.version to events. var withECSVersion = processing.WithFields(mapstr.M{ "ecs": mapstr.M{ @@ -60,7 +57,7 @@ func MetricbeatSettings(moduleNameSpace string) instance.Settings { if moduleNameSpace == "" { moduleNameSpace = "module" } - var runFlags = pflag.NewFlagSet(Name, pflag.ExitOnError) + runFlags := pflag.NewFlagSet(Name, pflag.ExitOnError) runFlags.AddGoFlag(flag.CommandLine.Lookup("system.hostfs")) cfgfile.AddAllowedBackwardsCompatibleFlag("system.hostfs") return instance.Settings{ @@ -82,7 +79,3 @@ func Initialize(settings instance.Settings) *cmd.BeatsRootCmd { rootCmd.TestCmd.AddCommand(test.GenTestModulesCmd(Name, "", beater.DefaultTestModulesCreator())) return rootCmd } - -func init() { - RootCmd = Initialize(MetricbeatSettings("")) -} diff --git a/metricbeat/main.go b/metricbeat/main.go index 5dcea740b21f..8515bca79d80 100644 --- a/metricbeat/main.go +++ b/metricbeat/main.go @@ -32,7 +32,7 @@ import ( ) func main() { - if err := cmd.RootCmd.Execute(); err != nil { + if err := cmd.Initialize(cmd.MetricbeatSettings("")).Execute(); err != nil { os.Exit(1) } } diff --git a/metricbeat/main_test.go b/metricbeat/main_test.go index 495ce5787e04..be50210575e7 100644 --- a/metricbeat/main_test.go +++ b/metricbeat/main_test.go @@ -21,21 +21,27 @@ package main import ( "flag" + "os" "testing" "github.com/elastic/beats/v7/libbeat/cfgfile" + cmd "github.com/elastic/beats/v7/libbeat/cmd" "github.com/elastic/beats/v7/libbeat/tests/system/template" - "github.com/elastic/beats/v7/metricbeat/cmd" + mbcmd "github.com/elastic/beats/v7/metricbeat/cmd" ) -var systemTest *bool +var ( + systemTest *bool + mbCommand *cmd.BeatsRootCmd +) func init() { testing.Init() systemTest = flag.Bool("systemTest", false, "Set to true when running system tests") - cmd.RootCmd.PersistentFlags().AddGoFlag(flag.CommandLine.Lookup("systemTest")) + mbCommand = mbcmd.Initialize(mbcmd.MetricbeatSettings("")) + mbCommand.PersistentFlags().AddGoFlag(flag.CommandLine.Lookup("systemTest")) cfgfile.AddAllowedBackwardsCompatibleFlag("systemTest") - cmd.RootCmd.PersistentFlags().AddGoFlag(flag.CommandLine.Lookup("test.coverprofile")) + mbCommand.PersistentFlags().AddGoFlag(flag.CommandLine.Lookup("test.coverprofile")) cfgfile.AddAllowedBackwardsCompatibleFlag("test.coverprofile") } @@ -43,10 +49,12 @@ func init() { func TestSystem(t *testing.T) { cfgfile.ConvertFlagsForBackwardsCompatibility() if *systemTest { - main() + if err := mbCommand.Execute(); err != nil { + os.Exit(1) + } } } func TestTemplate(t *testing.T) { - template.TestTemplate(t, cmd.Name, false) + template.TestTemplate(t, mbCommand.Name(), false) } diff --git a/x-pack/agentbeat/main.go b/x-pack/agentbeat/main.go index f96031ec081e..44cc6ce33062 100644 --- a/x-pack/agentbeat/main.go +++ b/x-pack/agentbeat/main.go @@ -42,7 +42,7 @@ into a single agentbeat binary.`, prepareCommand(auditbeat.RootCmd), prepareCommand(filebeat.Filebeat()), prepareCommand(heartbeat.RootCmd), - prepareCommand(metricbeat.RootCmd), + prepareCommand(metricbeat.Initialize()), prepareCommand(osquerybeat.RootCmd), prepareCommand(packetbeat.RootCmd), ) diff --git a/x-pack/libbeat/management/tests/mbtest/metricbeat_v2_test.go b/x-pack/libbeat/management/tests/mbtest/metricbeat_v2_test.go index fb8542514c2c..4ffa583120b4 100644 --- a/x-pack/libbeat/management/tests/mbtest/metricbeat_v2_test.go +++ b/x-pack/libbeat/management/tests/mbtest/metricbeat_v2_test.go @@ -34,8 +34,9 @@ var expectedMBStreams = &proto.UnitExpectedConfig{ } func TestSingleMetricbeatMetricsetWithProcessors(t *testing.T) { - tests.InitBeatsForTest(t, cmd.RootCmd) - var mbStreams = []*proto.Stream{ + mbCmd := cmd.Initialize() + tests.InitBeatsForTest(t, mbCmd) + mbStreams := []*proto.Stream{ { Id: "system/metrics-system.cpu-default-system", DataStream: &proto.DataStream{ @@ -79,7 +80,7 @@ func TestSingleMetricbeatMetricsetWithProcessors(t *testing.T) { go func() { t.Logf("Running beats...") - err := cmd.RootCmd.Execute() + err := mbCmd.Execute() require.NoError(t, err) }() diff --git a/x-pack/libbeat/management/tests/mbtest/system/process_integration_test.go b/x-pack/libbeat/management/tests/mbtest/system/process_integration_test.go index 660e95255582..3f9361823337 100644 --- a/x-pack/libbeat/management/tests/mbtest/system/process_integration_test.go +++ b/x-pack/libbeat/management/tests/mbtest/system/process_integration_test.go @@ -37,7 +37,8 @@ func TestProcessStatusReporter(t *testing.T) { unitOutID := mock.NewID() token := mock.NewID() - tests.InitBeatsForTest(t, cmd.RootCmd) + mbCmd := cmd.Initialize() + tests.InitBeatsForTest(t, mbCmd) filename := fmt.Sprintf("test-%d", time.Now().Unix()) outPath := filepath.Join(t.TempDir(), filename) @@ -122,7 +123,7 @@ func TestProcessStatusReporter(t *testing.T) { go func() { t.Logf("Running beats...") - err := cmd.RootCmd.Execute() + err := mbCmd.Execute() require.NoError(t, err) }() diff --git a/x-pack/metricbeat/cmd/root.go b/x-pack/metricbeat/cmd/root.go index 47e169b1c956..76ca40ddf131 100644 --- a/x-pack/metricbeat/cmd/root.go +++ b/x-pack/metricbeat/cmd/root.go @@ -33,9 +33,6 @@ const ( Name = "metricbeat" ) -// RootCmd to handle beats cli -var RootCmd *cmd.BeatsRootCmd - // withECSVersion is a modifier that adds ecs.version to events. var withECSVersion = processing.WithFields(mapstr.M{ "ecs": mapstr.M{ @@ -43,7 +40,7 @@ var withECSVersion = processing.WithFields(mapstr.M{ }, }) -func init() { +func Initialize() *cmd.BeatsRootCmd { globalProcs, err := processors.NewPluginConfigFromList(defaultProcessors()) if err != nil { // these are hard-coded, shouldn't fail panic(fmt.Errorf("error creating global processors: %w", err)) @@ -51,12 +48,13 @@ func init() { settings := mbcmd.MetricbeatSettings("") settings.ElasticLicensed = true settings.Processing = processing.MakeDefaultSupport(true, globalProcs, withECSVersion, processing.WithHost, processing.WithAgentMeta()) - RootCmd = cmd.GenRootCmdWithSettings(beater.DefaultCreator(), settings) - RootCmd.AddCommand(cmd.GenModulesCmd(Name, "", mbcmd.BuildModulesManager)) - RootCmd.TestCmd.AddCommand(test.GenTestModulesCmd(Name, "", beater.DefaultTestModulesCreator())) - RootCmd.PersistentPreRun = func(cmd *cobra.Command, args []string) { + rootCmd := cmd.GenRootCmdWithSettings(beater.DefaultCreator(), settings) + rootCmd.AddCommand(cmd.GenModulesCmd(Name, "", mbcmd.BuildModulesManager)) + rootCmd.TestCmd.AddCommand(test.GenTestModulesCmd(Name, "", beater.DefaultTestModulesCreator())) + rootCmd.PersistentPreRun = func(cmd *cobra.Command, args []string) { management.ConfigTransform.SetTransform(metricbeatCfg) } + return rootCmd } func defaultProcessors() []mapstr.M { diff --git a/x-pack/metricbeat/main.go b/x-pack/metricbeat/main.go index 92469da9c174..08afded3254f 100644 --- a/x-pack/metricbeat/main.go +++ b/x-pack/metricbeat/main.go @@ -19,7 +19,7 @@ import ( ) func main() { - if err := cmd.RootCmd.Execute(); err != nil { + if err := cmd.Initialize().Execute(); err != nil { os.Exit(1) } } diff --git a/x-pack/metricbeat/main_test.go b/x-pack/metricbeat/main_test.go index e96a9932765c..906782e1f5a5 100644 --- a/x-pack/metricbeat/main_test.go +++ b/x-pack/metricbeat/main_test.go @@ -6,21 +6,27 @@ package main // This file is mandatory as otherwise the metricbeat.test binary is not generated correctly. import ( "flag" + "os" "testing" "github.com/elastic/beats/v7/libbeat/cfgfile" + cmd "github.com/elastic/beats/v7/libbeat/cmd" "github.com/elastic/beats/v7/libbeat/tests/system/template" - "github.com/elastic/beats/v7/x-pack/metricbeat/cmd" + mbcmd "github.com/elastic/beats/v7/x-pack/metricbeat/cmd" ) -var systemTest *bool +var ( + systemTest *bool + mbCommand *cmd.BeatsRootCmd +) func init() { testing.Init() systemTest = flag.Bool("systemTest", false, "Set to true when running system tests") - cmd.RootCmd.PersistentFlags().AddGoFlag(flag.CommandLine.Lookup("systemTest")) + mbCommand = mbcmd.Initialize() + mbCommand.PersistentFlags().AddGoFlag(flag.CommandLine.Lookup("systemTest")) cfgfile.AddAllowedBackwardsCompatibleFlag("systemTest") - cmd.RootCmd.PersistentFlags().AddGoFlag(flag.CommandLine.Lookup("test.coverprofile")) + mbCommand.PersistentFlags().AddGoFlag(flag.CommandLine.Lookup("test.coverprofile")) cfgfile.AddAllowedBackwardsCompatibleFlag("test.coverprofile") } @@ -28,10 +34,12 @@ func init() { func TestSystem(t *testing.T) { cfgfile.ConvertFlagsForBackwardsCompatibility() if *systemTest { - main() + if err := mbCommand.Execute(); err != nil { + os.Exit(1) + } } } func TestTemplate(t *testing.T) { - template.TestTemplate(t, cmd.Name, true) + template.TestTemplate(t, mbCommand.Name(), true) } From 444b8e48f47479ddec5c7e8622b557d309d03ab8 Mon Sep 17 00:00:00 2001 From: Mauri de Souza Meneguzzo Date: Mon, 2 Dec 2024 12:35:30 -0300 Subject: [PATCH 04/48] metricbeat: suppress error when RAID metrics are enabled on non-RAID system (#41825) * metricbeat: return partial metrics errror when RAID metrics are enabled on non-RAID system When the Linux Metrics integration (beta) is installed with the RAID metrics option enabled it causes an error if the host does not have a RAID configuration. This error causes the Agent to go into a degraded state. This happens because we report not having `/sys/block/md*` devices as an error, this only means that no RAID configuration is in place. Instead, return a partial metrics error for this case. This still shows up in the agent status but does not cause a degraded state. * use partial metrics error * fix linter issue with iface assertion --- .../module/system/raid/blockinfo/getdev.go | 12 +++++------ metricbeat/module/system/raid/raid.go | 7 +++++-- metricbeat/module/system/raid/raid_test.go | 20 +++++++++++++++++++ 3 files changed, 30 insertions(+), 9 deletions(-) diff --git a/metricbeat/module/system/raid/blockinfo/getdev.go b/metricbeat/module/system/raid/blockinfo/getdev.go index 02527c806367..7c92b0fc8815 100644 --- a/metricbeat/module/system/raid/blockinfo/getdev.go +++ b/metricbeat/module/system/raid/blockinfo/getdev.go @@ -19,14 +19,15 @@ package blockinfo import ( "fmt" - "io/ioutil" "os" "path/filepath" + + "github.com/elastic/beats/v7/metricbeat/mb" ) // ListAll lists all the multi-disk devices in a RAID array func ListAll(path string) ([]MDDevice, error) { - dir, err := ioutil.ReadDir(path) + dir, err := os.ReadDir(path) if err != nil { return nil, fmt.Errorf("could not read directory: %w", err) } @@ -44,7 +45,7 @@ func ListAll(path string) ([]MDDevice, error) { } if len(mds) == 0 { - return nil, fmt.Errorf("no matches from path %s", path) + return nil, mb.PartialMetricsError{Err: fmt.Errorf("no RAID devices found. You have probably enabled the RAID metrics on a non-RAID system.")} } return mds, nil @@ -69,8 +70,5 @@ func getMDDevice(path string) (MDDevice, error) { // Right now, we're doing this by looking for an `md` directory in the device dir. func isMD(path string) bool { _, err := os.Stat(filepath.Join(path, "md")) - if err != nil { - return false - } - return true + return err == nil } diff --git a/metricbeat/module/system/raid/raid.go b/metricbeat/module/system/raid/raid.go index 191027657d7f..7b07e36c4d2d 100644 --- a/metricbeat/module/system/raid/raid.go +++ b/metricbeat/module/system/raid/raid.go @@ -41,8 +41,11 @@ type MetricSet struct { // New creates a new instance of the raid metricset. func New(base mb.BaseMetricSet) (mb.MetricSet, error) { + sys, ok := base.Module().(resolve.Resolver) + if !ok { + return nil, fmt.Errorf("unexpected module type: %T", base.Module()) + } - sys := base.Module().(resolve.Resolver) return &MetricSet{ BaseMetricSet: base, @@ -62,7 +65,7 @@ func blockto1024(b int64) int64 { func (m *MetricSet) Fetch(r mb.ReporterV2) error { devices, err := blockinfo.ListAll(m.mod.ResolveHostFS("/sys/block")) if err != nil { - return fmt.Errorf("failed to parse sysfs: %w", err) + return fmt.Errorf("failed to list RAID devices: %w", err) } for _, blockDev := range devices { diff --git a/metricbeat/module/system/raid/raid_test.go b/metricbeat/module/system/raid/raid_test.go index 4c35394413af..28b3358f685d 100644 --- a/metricbeat/module/system/raid/raid_test.go +++ b/metricbeat/module/system/raid/raid_test.go @@ -18,10 +18,14 @@ package raid import ( + "errors" + "os" + "path/filepath" "testing" "github.com/stretchr/testify/assert" + "github.com/elastic/beats/v7/metricbeat/mb" mbtest "github.com/elastic/beats/v7/metricbeat/mb/testing" _ "github.com/elastic/beats/v7/metricbeat/module/system" ) @@ -46,6 +50,22 @@ func TestFetch(t *testing.T) { events[0].BeatEvent("system", "raid").Fields.StringToPrint()) } +func TestFetchNoRAID(t *testing.T) { + // Ensure that we return partial metrics when no RAID devices are present. + tmpDir := t.TempDir() + assert.NoError(t, os.MkdirAll(filepath.Join(tmpDir, "sys/block"), 0755)) + c := getConfig() + c["hostfs"] = tmpDir + + f := mbtest.NewReportingMetricSetV2Error(t, c) + events, errs := mbtest.ReportingFetchV2Error(f) + + assert.Len(t, errs, 1) + assert.ErrorAs(t, errors.Join(errs...), &mb.PartialMetricsError{}) + assert.Contains(t, errors.Join(errs...).Error(), "failed to list RAID devices: no RAID devices found. You have probably enabled the RAID metrics on a non-RAID system.") + assert.Empty(t, events) +} + func getConfig() map[string]interface{} { return map[string]interface{}{ "module": "system", From 0631d8b1ae10e0d25a0ebbc70a8118f858b08631 Mon Sep 17 00:00:00 2001 From: Dan Kortschak Date: Tue, 3 Dec 2024 16:26:57 +1030 Subject: [PATCH 05/48] x-pack/filebeat/input/cel: add evaluation state dump debugging feature (#41335) This allows a program to conditionally dump a complete set of evaluation states from a program in the case that it fails, allowing a trace of execution leading to the failure. --- CHANGELOG.next.asciidoc | 1 + .../filebeat/docs/inputs/input-cel.asciidoc | 20 +++ x-pack/filebeat/input/cel/config.go | 19 ++- x-pack/filebeat/input/cel/input.go | 84 +++++++++++- x-pack/filebeat/input/cel/input_test.go | 123 ++++++++++++++++-- 5 files changed, 226 insertions(+), 21 deletions(-) diff --git a/CHANGELOG.next.asciidoc b/CHANGELOG.next.asciidoc index b4e618e2da4c..28a2949e7770 100644 --- a/CHANGELOG.next.asciidoc +++ b/CHANGELOG.next.asciidoc @@ -347,6 +347,7 @@ https://github.com/elastic/beats/compare/v8.8.1\...main[Check the HEAD diff] - Add ability to remove request trace logs from http_endpoint input. {pull}40005[40005] - Add ability to remove request trace logs from entityanalytics input. {pull}40004[40004] - Update CEL mito extensions to v1.16.0. {pull}41727[41727] +- Add evaluation state dump debugging option to CEL input. {pull}41335[41335] *Auditbeat* diff --git a/x-pack/filebeat/docs/inputs/input-cel.asciidoc b/x-pack/filebeat/docs/inputs/input-cel.asciidoc index a96e8df5f3dd..8e062025b248 100644 --- a/x-pack/filebeat/docs/inputs/input-cel.asciidoc +++ b/x-pack/filebeat/docs/inputs/input-cel.asciidoc @@ -795,6 +795,26 @@ This specifies fields in the `state` to be redacted prior to debug logging. Fiel This specifies whether fields should be replaced with a `*` or deleted entirely from messages sent to debug logs. If delete is `true`, fields will be deleted rather than replaced. +[float] +==== `failure_dump.enabled` + +It is possible to log CEL program evaluation failures to a local file-system for debugging configurations. +This option is enabled by setting `failure_dump.enabled` to true and setting the `failure_dump.filename` value. +To delete existing failure dumps, set `failure_dump.enabled` to false without unsetting the filename option. + +Enabling this option compromises security and should only be used for debugging. + +[float] +==== `failure_dump.filename` + +This specifies a directory path to write failure dumps to. If it is not empty and a CEL program evaluation fails, +the complete set of states for the CEL program's evaluation will be written as a JSON file, along with the error +that was reported. This option should only be used when debugging a failure as it imposes a significant performance +impact on the input and may potentially use large quantities of memory to hold the full set of states. If a failure +dump is configured, it is recommended that data input sizes be reduced to avoid excessive memory consumption, and +making dumps that are intractable to analysis. To delete existing failure dumps, set `failure_dump.enabled` to +false without unsetting the filename option. + [float] === Metrics diff --git a/x-pack/filebeat/input/cel/config.go b/x-pack/filebeat/input/cel/config.go index b04b78457198..aee095b199b9 100644 --- a/x-pack/filebeat/input/cel/config.go +++ b/x-pack/filebeat/input/cel/config.go @@ -58,6 +58,9 @@ type config struct { // Resource is the configuration for establishing an // HTTP request or for locating a local resource. Resource *ResourceConfig `config:"resource" validate:"required"` + + // FailureDump configures failure dump behaviour. + FailureDump *dumpConfig `config:"failure_dump"` } type redact struct { @@ -69,6 +72,19 @@ type redact struct { Delete bool `config:"delete"` } +// dumpConfig configures the CEL program to retain +// the full evaluation state using the cel.OptTrackState +// option. The state is written to a file in the path if +// the evaluation fails. +type dumpConfig struct { + Enabled *bool `config:"enabled"` + Filename string `config:"filename"` +} + +func (t *dumpConfig) enabled() bool { + return t != nil && (t.Enabled == nil || *t.Enabled) +} + func (c config) Validate() error { if c.Redact == nil { logp.L().Named("input.cel").Warn("missing recommended 'redact' configuration: " + @@ -89,7 +105,8 @@ func (c config) Validate() error { if len(c.Regexps) != 0 { patterns = map[string]*regexp.Regexp{".": nil} } - _, _, err = newProgram(context.Background(), c.Program, root, nil, &http.Client{}, nil, nil, patterns, c.XSDs, logp.L().Named("input.cel"), nil) + wantDump := c.FailureDump.enabled() && c.FailureDump.Filename != "" + _, _, err = newProgram(context.Background(), c.Program, root, nil, &http.Client{}, nil, nil, patterns, c.XSDs, logp.L().Named("input.cel"), nil, wantDump) if err != nil { return fmt.Errorf("failed to check program: %w", err) } diff --git a/x-pack/filebeat/input/cel/input.go b/x-pack/filebeat/input/cel/input.go index ff4f1dccf51f..97ab8c9bee05 100644 --- a/x-pack/filebeat/input/cel/input.go +++ b/x-pack/filebeat/input/cel/input.go @@ -10,6 +10,7 @@ package cel import ( "compress/gzip" "context" + "encoding/json" "errors" "fmt" "io" @@ -166,7 +167,8 @@ func (i input) run(env v2.Context, src *source, cursor map[string]interface{}, p Password: cfg.Auth.Basic.Password, } } - prg, ast, err := newProgram(ctx, cfg.Program, root, getEnv(cfg.AllowedEnvironment), client, limiter, auth, patterns, cfg.XSDs, log, trace) + wantDump := cfg.FailureDump.enabled() && cfg.FailureDump.Filename != "" + prg, ast, err := newProgram(ctx, cfg.Program, root, getEnv(cfg.AllowedEnvironment), client, limiter, auth, patterns, cfg.XSDs, log, trace, wantDump) if err != nil { return err } @@ -251,12 +253,25 @@ func (i input) run(env v2.Context, src *source, cursor map[string]interface{}, p log.Debugw("request state", logp.Namespace("cel"), "state", redactor{state: state, cfg: cfg.Redact}) metrics.executions.Add(1) start := i.now().In(time.UTC) - state, err = evalWith(ctx, prg, ast, state, start) + state, err = evalWith(ctx, prg, ast, state, start, wantDump) log.Debugw("response state", logp.Namespace("cel"), "state", redactor{state: state, cfg: cfg.Redact}) if err != nil { + var dump dumpError switch { case errors.Is(err, context.Canceled), errors.Is(err, context.DeadlineExceeded): return err + case errors.As(err, &dump): + path := strings.ReplaceAll(cfg.FailureDump.Filename, "*", sanitizeFileName(env.IDWithoutName)) + dir := filepath.Dir(path) + base := filepath.Base(path) + ext := filepath.Ext(base) + prefix := strings.TrimSuffix(base, ext) + path = filepath.Join(dir, prefix+"-"+i.now().In(time.UTC).Format("2006-01-02T15-04-05.000")+ext) + log.Debugw("writing failure dump file", "path", path) + err := dump.writeToFile(path) + if err != nil { + log.Errorw("failed to write failure dump", "path", path, "error", err) + } } log.Errorw("failed evaluation", "error", err) env.UpdateStatus(status.Degraded, "failed evaluation: "+err.Error()) @@ -785,6 +800,26 @@ func newClient(ctx context.Context, cfg config, log *logp.Logger, reg *monitorin } } } + if !cfg.FailureDump.enabled() && cfg.FailureDump != nil && cfg.FailureDump.Filename != "" { + // We have a fail-dump name, but we are not enabled, + // so remove all dumps we own. + err = os.Remove(cfg.FailureDump.Filename) + if err != nil && !errors.Is(err, fs.ErrNotExist) { + log.Errorw("failed to remove request trace log", "path", cfg.FailureDump.Filename, "error", err) + } + ext := filepath.Ext(cfg.FailureDump.Filename) + base := strings.TrimSuffix(cfg.FailureDump.Filename, ext) + paths, err := filepath.Glob(base + "-" + lumberjackTimestamp + ext) + if err != nil { + log.Errorw("failed to collect request trace log path names", "error", err) + } + for _, p := range paths { + err = os.Remove(p) + if err != nil && !errors.Is(err, fs.ErrNotExist) { + log.Errorw("failed to remove request trace log", "path", p, "error", err) + } + } + } if reg != nil { c.Transport = httpmon.NewMetricsRoundTripper(c.Transport, reg) @@ -1004,7 +1039,7 @@ func getEnv(allowed []string) map[string]string { return env } -func newProgram(ctx context.Context, src, root string, vars map[string]string, client *http.Client, limiter *rate.Limiter, auth *lib.BasicAuth, patterns map[string]*regexp.Regexp, xsd map[string]string, log *logp.Logger, trace *httplog.LoggingRoundTripper) (cel.Program, *cel.Ast, error) { +func newProgram(ctx context.Context, src, root string, vars map[string]string, client *http.Client, limiter *rate.Limiter, auth *lib.BasicAuth, patterns map[string]*regexp.Regexp, xsd map[string]string, log *logp.Logger, trace *httplog.LoggingRoundTripper, details bool) (cel.Program, *cel.Ast, error) { xml, err := lib.XML(nil, xsd) if err != nil { return nil, nil, fmt.Errorf("failed to build xml type hints: %w", err) @@ -1043,7 +1078,11 @@ func newProgram(ctx context.Context, src, root string, vars map[string]string, c return nil, nil, fmt.Errorf("failed compilation: %w", iss.Err()) } - prg, err := env.Program(ast) + var progOpts []cel.ProgramOption + if details { + progOpts = []cel.ProgramOption{cel.EvalOptions(cel.OptTrackState)} + } + prg, err := env.Program(ast, progOpts...) if err != nil { return nil, nil, fmt.Errorf("failed program instantiation: %w", err) } @@ -1065,8 +1104,8 @@ func debug(log *logp.Logger, trace *httplog.LoggingRoundTripper) func(string, an } } -func evalWith(ctx context.Context, prg cel.Program, ast *cel.Ast, state map[string]interface{}, now time.Time) (map[string]interface{}, error) { - out, _, err := prg.ContextEval(ctx, map[string]interface{}{ +func evalWith(ctx context.Context, prg cel.Program, ast *cel.Ast, state map[string]interface{}, now time.Time, details bool) (map[string]interface{}, error) { + out, det, err := prg.ContextEval(ctx, map[string]interface{}{ // Replace global program "now" with current time. This is necessary // as the lib.Time now global is static at program instantiation time // which will persist over multiple evaluations. The lib.Time behaviour @@ -1081,6 +1120,9 @@ func evalWith(ctx context.Context, prg cel.Program, ast *cel.Ast, state map[stri }) if err != nil { err = lib.DecoratedError{AST: ast, Err: err} + if details { + err = dumpError{error: err, dump: lib.NewDump(ast, det)} + } } if e := ctx.Err(); e != nil { err = e @@ -1109,6 +1151,36 @@ func evalWith(ctx context.Context, prg cel.Program, ast *cel.Ast, state map[stri } } +// dumpError is an evaluation state dump associated with an error. +type dumpError struct { + error + dump *lib.Dump +} + +func (e dumpError) writeToFile(path string) (err error) { + err = os.MkdirAll(filepath.Dir(path), 0o700) + if err != nil { + return err + } + f, err := os.Create(path) + if err != nil { + return err + } + defer func() { + err = errors.Join(err, f.Sync(), f.Close()) + }() + enc := json.NewEncoder(f) + enc.SetEscapeHTML(false) + type dump struct { + Error string `json:"error"` + State []lib.NodeValue `json:"state"` + } + return enc.Encode(dump{ + Error: e.Error(), + State: e.dump.NodeValues(), + }) +} + // clearWantMore sets the state to not request additional work in a periodic evaluation. // It leaves state intact if there is no "want_more" element, and sets the element to false // if there is. This is necessary instead of just doing delete(state, "want_more") as diff --git a/x-pack/filebeat/input/cel/input_test.go b/x-pack/filebeat/input/cel/input_test.go index 0d91710ca093..143402d98347 100644 --- a/x-pack/filebeat/input/cel/input_test.go +++ b/x-pack/filebeat/input/cel/input_test.go @@ -45,6 +45,7 @@ var inputTests = []struct { want []map[string]interface{} wantCursor []map[string]interface{} wantErr error + prepare func() error wantFile string wantNoFile string }{ @@ -1685,6 +1686,88 @@ var inputTests = []struct { }, }}, }, + { + name: "dump_no_error", + config: map[string]interface{}{ + "interval": 1, + "program": `{"events":[{"message":{"value": try(debug("divide by zero", 0/0))}}]}`, + "state": nil, + "resource": map[string]interface{}{ + "url": "", + }, + "failure_dump": map[string]interface{}{ + "enabled": true, + "filename": "failure_dumps/dump.json", + }, + }, + time: func() time.Time { return time.Date(2010, 2, 8, 0, 0, 0, 0, time.UTC) }, + wantNoFile: filepath.Join("failure_dumps", "dump-2010-02-08T00-00-00.000.json"), + want: []map[string]interface{}{{ + "message": map[string]interface{}{ + "value": "division by zero", + }, + }}, + }, + { + name: "dump_error", + config: map[string]interface{}{ + "interval": 1, + "program": `{"events":[{"message":{"value": debug("divide by zero", 0/0)}}]}`, + "state": nil, + "resource": map[string]interface{}{ + "url": "", + }, + "failure_dump": map[string]interface{}{ + "enabled": true, + "filename": "failure_dumps/dump.json", + }, + }, + time: func() time.Time { return time.Date(2010, 2, 9, 0, 0, 0, 0, time.UTC) }, + wantFile: filepath.Join("failure_dumps", "dump-2010-02-09T00-00-00.000.json"), // One day after the no dump case. + want: []map[string]interface{}{ + { + "error": map[string]interface{}{ + "message": `failed eval: ERROR: :1:58: division by zero + | {"events":[{"message":{"value": debug("divide by zero", 0/0)}}]} + | .........................................................^`, + }, + }, + }, + }, + { + name: "dump_error_delete", + config: map[string]interface{}{ + "interval": 1, + "program": `{"events":[{"message":{"value": debug("divide by zero", 0/0)}}]}`, + "state": nil, + "resource": map[string]interface{}{ + "url": "", + }, + "failure_dump": map[string]interface{}{ + "enabled": false, // We have a name but are disabled, so delete. + "filename": "failure_dumps/dump.json", + }, + }, + time: func() time.Time { return time.Date(2010, 2, 9, 0, 0, 0, 0, time.UTC) }, + prepare: func() error { + // Make a file that the configuration should delete. + err := os.MkdirAll("failure_dumps", 0o700) + if err != nil { + return err + } + return os.WriteFile(filepath.Join("failure_dumps", "dump-2010-02-09T00-00-00.000.json"), nil, 0o600) + }, + wantNoFile: filepath.Join("failure_dumps", "dump-2010-02-09T00-00-00.000.json"), // One day after the no dump case. + want: []map[string]interface{}{ + { + "error": map[string]interface{}{ + "message": `failed eval: ERROR: :1:58: division by zero + | {"events":[{"message":{"value": debug("divide by zero", 0/0)}}]} + | .........................................................^`, + }, + }, + }, + }, // not yet done from httpjson (some are redundant since they are compositional products). // @@ -1708,6 +1791,11 @@ func TestInput(t *testing.T) { os.Setenv("CELTESTENVVAR", "TESTVALUE") os.Setenv("DISALLOWEDCELTESTENVVAR", "DISALLOWEDTESTVALUE") + err := os.RemoveAll("failure_dumps") + if err != nil { + t.Fatalf("failed to remove failure_dumps directory: %v", err) + } + logp.TestingSetup() for _, test := range inputTests { t.Run(test.name, func(t *testing.T) { @@ -1718,6 +1806,13 @@ func TestInput(t *testing.T) { t.Skip("skipping remote endpoint test") } + if test.prepare != nil { + err := test.prepare() + if err != nil { + t.Fatalf("unexpected from prepare(): %v", err) + } + } + if test.server != nil { test.server(t, test.handler, test.config) } @@ -1770,6 +1865,20 @@ func TestInput(t *testing.T) { if fmt.Sprint(err) != fmt.Sprint(test.wantErr) { t.Errorf("unexpected error from running input: got:%v want:%v", err, test.wantErr) } + if test.wantFile != "" { + if _, err := os.Stat(filepath.Join(tempDir, test.wantFile)); err != nil { + t.Errorf("expected log file not found: %v", err) + } + } + if test.wantNoFile != "" { + paths, err := filepath.Glob(filepath.Join(tempDir, test.wantNoFile)) + if err != nil { + t.Fatalf("unexpected error calling filepath.Glob(%q): %v", test.wantNoFile, err) + } + if len(paths) != 0 { + t.Errorf("unexpected files found: %v", paths) + } + } if test.wantErr != nil { return } @@ -1802,20 +1911,6 @@ func TestInput(t *testing.T) { t.Errorf("unexpected cursor for event %d: got:- want:+\n%s", i, cmp.Diff(got, test.wantCursor[i])) } } - if test.wantFile != "" { - if _, err := os.Stat(filepath.Join(tempDir, test.wantFile)); err != nil { - t.Errorf("expected log file not found: %v", err) - } - } - if test.wantNoFile != "" { - paths, err := filepath.Glob(filepath.Join(tempDir, test.wantNoFile)) - if err != nil { - t.Fatalf("unexpected error calling filepath.Glob(%q): %v", test.wantNoFile, err) - } - if len(paths) != 0 { - t.Errorf("unexpected files found: %v", paths) - } - } }) } } From 01cc1344efe0c954e9267a21eb7bcfc256e9eaae Mon Sep 17 00:00:00 2001 From: ShourieG Date: Tue, 3 Dec 2024 11:50:48 +0530 Subject: [PATCH 06/48] [filebeat][gcs] - Refactor & cleanup with updates to some default values and docs (#41834) --- CHANGELOG.next.asciidoc | 1 + .../filebeat/docs/inputs/input-gcs.asciidoc | 18 ++++----- x-pack/filebeat/input/gcs/client.go | 4 +- x-pack/filebeat/input/gcs/config.go | 37 ++++++++++++------ x-pack/filebeat/input/gcs/input.go | 39 +++++-------------- x-pack/filebeat/input/gcs/input_stateless.go | 1 - x-pack/filebeat/input/gcs/input_test.go | 6 +-- 7 files changed, 46 insertions(+), 60 deletions(-) diff --git a/CHANGELOG.next.asciidoc b/CHANGELOG.next.asciidoc index 28a2949e7770..7b7a351e2027 100644 --- a/CHANGELOG.next.asciidoc +++ b/CHANGELOG.next.asciidoc @@ -346,6 +346,7 @@ https://github.com/elastic/beats/compare/v8.8.1\...main[Check the HEAD diff] - Add support for Journald in the System module. {pull}41555[41555] - Add ability to remove request trace logs from http_endpoint input. {pull}40005[40005] - Add ability to remove request trace logs from entityanalytics input. {pull}40004[40004] +- Refactor & cleanup with updates to default values and documentation. {pull}41834[41834] - Update CEL mito extensions to v1.16.0. {pull}41727[41727] - Add evaluation state dump debugging option to CEL input. {pull}41335[41335] diff --git a/x-pack/filebeat/docs/inputs/input-gcs.asciidoc b/x-pack/filebeat/docs/inputs/input-gcs.asciidoc index 23ac0e021c6a..2a762ddec18a 100644 --- a/x-pack/filebeat/docs/inputs/input-gcs.asciidoc +++ b/x-pack/filebeat/docs/inputs/input-gcs.asciidoc @@ -10,9 +10,7 @@ ++++ Use the `google cloud storage input` to read content from files stored in buckets which reside on your Google Cloud. -The input can be configured to work with and without polling, though currently, if polling is disabled it will only -perform a one time passthrough, list the file contents and end the process. Polling is generally recommented for most cases -even though it can get expensive with dealing with a very large number of files. +The input can be configured to work with and without polling, though if polling is disabled it will only perform a single collection of data, list the file contents and end the process. *To mitigate errors and ensure a stable processing environment, this input employs the following features :* @@ -66,12 +64,11 @@ many buckets as we deem fit. We are also able to configure the attributes `max_w then be applied to all buckets which do not specify any of these attributes explicitly. NOTE: If the attributes `max_workers`, `poll`, `poll_interval` and `bucket_timeout` are specified at the root level, these can still be overridden at the bucket level with -different values, thus offering extensive flexibility and customization. Examples <> show this behaviour. +different values, thus offering extensive flexibility and customization. Examples <> show this behavior. On receiving this config the google cloud storage input will connect to the service and retrieve a `Storage Client` using the given `bucket_name` and `auth.credentials_file`, then it will spawn two main go-routines, one for each bucket. After this each of these routines (threads) will initialize a scheduler -which will in turn use the `max_workers` value to initialize an in-memory worker pool (thread pool) with `3` `workers` available. Basically that equates to two instances of a worker pool, -one per bucket, each having 3 workers. These `workers` will be responsible for performing `jobs` that process a file (in this case read and output the contents of a file). +which will in turn use the `max_workers` value to initialize an in-memory worker pool (thread pool) with `3` `workers` available. Basically that equates to two instances of a worker pool, one per bucket, each having 3 workers. These `workers` will be responsible for performing `jobs` that process a file (in this case read and output the contents of a file). NOTE: The scheduler is responsible for scheduling jobs, and uses the `maximum available workers` in the pool, at each iteration, to decide the number of files to retrieve and process. This keeps work distribution efficient. The scheduler uses `poll_interval` attribute value to decide how long to wait after each iteration. The `bucket_timeout` value is used to timeout calls to the bucket list api if it exceeds the given value. Each iteration consists of processing a certain number of files, decided by the `maximum available workers` value. @@ -213,7 +210,7 @@ This is a specific subfield of a bucket. It specifies the bucket name. This attribute defines the maximum amount of time after which a bucket operation will give and stop if no response is recieved (example: reading a file / listing a file). It can be defined in the following formats : `{{x}}s`, `{{x}}m`, `{{x}}h`, here `s = seconds`, `m = minutes` and `h = hours`. The value `{{x}}` can be anything we wish. -If no value is specified for this, by default its initialized to `50 seconds`. This attribute can be specified both at the root level of the configuration as well at the bucket level. The bucket level values will always take priority and override the root level values if both are specified. The value of `bucket_timeout` that should be used depends on the size of the files and the network speed. If the timeout is too low, the input will not be able to read the file completely and `context_deadline_exceeded` errors will be seen in the logs. If the timeout is too high, the input will wait for a long time for the file to be read, which can cause the input to be slow. The ratio between the `bucket_timeout` and `poll_interval` should be considered while setting both the values. A low `poll_interval` and a very high `bucket_timeout` can cause resource utilization issues as schedule ops will be spawned every poll iteration. If previous poll ops are still running, this could result in concurrently running ops and so could cause a bottleneck over time. +If no value is specified for this, by default its initialized to `120 seconds`. This attribute can be specified both at the root level of the configuration as well at the bucket level. The bucket level values will always take priority and override the root level values if both are specified. The value of `bucket_timeout` that should be used depends on the size of the files and the network speed. If the timeout is too low, the input will not be able to read the file completely and `context_deadline_exceeded` errors will be seen in the logs. If the timeout is too high, the input will wait for a long time for the file to be read, which can cause the input to be slow. The ratio between the `bucket_timeout` and `poll_interval` should be considered while setting both the values. A low `poll_interval` and a very high `bucket_timeout` can cause resource utilization issues as schedule ops will be spawned every poll iteration. If previous poll ops are still running, this could result in concurrently running ops and so could cause a bottleneck over time. [id="attrib-max_workers-gcs"] [float] @@ -228,9 +225,8 @@ NOTE: The value of `max_workers` is tied to the `batch_size` currently to ensure [float] ==== `poll` -This attribute informs the scheduler whether to keep polling for new files or not. Default value of this is `false`, so it will not keep polling if not explicitly -specified. This attribute can be specified both at the root level of the configuration as well at the bucket level. The bucket level values will always -take priority and override the root level values if both are specified. +This attribute informs the scheduler whether to keep polling for new files or not. Default value of this is set to `true`. This attribute can be specified both at the +root level of the configuration as well at the bucket level. The bucket level values will always take priority and override the root level values if both are specified. [id="attrib-poll_interval-gcs"] [float] @@ -238,7 +234,7 @@ take priority and override the root level values if both are specified. This attribute defines the maximum amount of time after which the internal scheduler will make the polling call for the next set of objects/files. It can be defined in the following formats : `{{x}}s`, `{{x}}m`, `{{x}}h`, here `s = seconds`, `m = minutes` and `h = hours`. The value `{{x}}` can be anything we wish. -Example : `10s` would mean we would like the polling to occur every 10 seconds. If no value is specified for this, by default its initialized to `300 seconds`. +Example : `10s` would mean we would like the polling to occur every 10 seconds. If no value is specified for this, by default its initialized to `5 minutes`. This attribute can be specified both at the root level of the configuration as well at the bucket level. The bucket level values will always take priority and override the root level values if both are specified. The `poll_interval` should be set to a value that is equal to the `bucket_timeout` value. This would ensure that another schedule operation is not started before the current buckets have all been processed. If the `poll_interval` is set to a value that is less than the `bucket_timeout`, then the input will start another schedule operation before the current one has finished, which can cause a bottleneck over time. Having a lower `poll_interval` can make the input faster at the cost of more resource utilization. diff --git a/x-pack/filebeat/input/gcs/client.go b/x-pack/filebeat/input/gcs/client.go index 7fd45d2d0a9c..1846e08c5ab0 100644 --- a/x-pack/filebeat/input/gcs/client.go +++ b/x-pack/filebeat/input/gcs/client.go @@ -12,11 +12,9 @@ import ( "cloud.google.com/go/storage" "golang.org/x/oauth2/google" "google.golang.org/api/option" - - "github.com/elastic/elastic-agent-libs/logp" ) -func fetchStorageClient(ctx context.Context, cfg config, log *logp.Logger) (*storage.Client, error) { +func fetchStorageClient(ctx context.Context, cfg config) (*storage.Client, error) { if cfg.AlternativeHost != "" { var h *url.URL h, err := url.Parse(cfg.AlternativeHost) diff --git a/x-pack/filebeat/input/gcs/config.go b/x-pack/filebeat/input/gcs/config.go index 6a7b93d5e479..64f64c69bc5f 100644 --- a/x-pack/filebeat/input/gcs/config.go +++ b/x-pack/filebeat/input/gcs/config.go @@ -28,16 +28,16 @@ type config struct { // Auth - Defines the authentication mechanism to be used for accessing the gcs bucket. Auth authConfig `config:"auth"` // MaxWorkers - Defines the maximum number of go routines that will be spawned. - MaxWorkers *int `config:"max_workers,omitempty" validate:"max=5000"` + MaxWorkers int `config:"max_workers" validate:"max=5000"` // Poll - Defines if polling should be performed on the input bucket source. - Poll *bool `config:"poll,omitempty"` + Poll bool `config:"poll"` // PollInterval - Defines the maximum amount of time to wait before polling for the next batch of objects from the bucket. - PollInterval *time.Duration `config:"poll_interval,omitempty"` + PollInterval time.Duration `config:"poll_interval"` // ParseJSON - Informs the publisher whether to parse & objectify json data or not. By default this is set to // false, since it can get expensive dealing with highly nested json data. - ParseJSON *bool `config:"parse_json,omitempty"` + ParseJSON bool `config:"parse_json"` // BucketTimeOut - Defines the maximum time that the sdk will wait for a bucket api response before timing out. - BucketTimeOut *time.Duration `config:"bucket_timeout,omitempty"` + BucketTimeOut time.Duration `config:"bucket_timeout"` // Buckets - Defines a list of buckets that will be polled for objects. Buckets []bucket `config:"buckets" validate:"required"` // FileSelectors - Defines a list of regex patterns that can be used to filter out objects from the bucket. @@ -49,17 +49,17 @@ type config struct { // ExpandEventListFromField - Defines the field name that will be used to expand the event into separate events. ExpandEventListFromField string `config:"expand_event_list_from_field"` // This field is only used for system test purposes, to override the HTTP endpoint. - AlternativeHost string `config:"alternative_host,omitempty"` + AlternativeHost string `config:"alternative_host"` } // bucket contains the config for each specific object storage bucket in the root account type bucket struct { Name string `config:"name" validate:"required"` - MaxWorkers *int `config:"max_workers,omitempty" validate:"max=5000"` - BucketTimeOut *time.Duration `config:"bucket_timeout,omitempty"` - Poll *bool `config:"poll,omitempty"` - PollInterval *time.Duration `config:"poll_interval,omitempty"` - ParseJSON *bool `config:"parse_json,omitempty"` + MaxWorkers *int `config:"max_workers" validate:"max=5000"` + BucketTimeOut *time.Duration `config:"bucket_timeout"` + Poll *bool `config:"poll"` + PollInterval *time.Duration `config:"poll_interval"` + ParseJSON *bool `config:"parse_json"` FileSelectors []fileSelectorConfig `config:"file_selectors"` ReaderConfig readerConfig `config:",inline"` TimeStampEpoch *int64 `config:"timestamp_epoch"` @@ -78,13 +78,15 @@ type readerConfig struct { Decoding decoderConfig `config:"decoding"` } +// authConfig defines the authentication mechanism to be used for accessing the gcs bucket. +// If either is configured the 'omitempty' tag will prevent the other option from being serialized in the config. type authConfig struct { CredentialsJSON *jsonCredentialsConfig `config:"credentials_json,omitempty"` CredentialsFile *fileCredentialsConfig `config:"credentials_file,omitempty"` } type fileCredentialsConfig struct { - Path string `config:"path,omitempty"` + Path string `config:"path"` } type jsonCredentialsConfig struct { AccountKey string `config:"account_key"` @@ -115,3 +117,14 @@ func (c authConfig) Validate() error { return fmt.Errorf("no authentication credentials were configured or detected " + "(credentials_file, credentials_json, and application default credentials (ADC))") } + +// defaultConfig returns the default configuration for the input +func defaultConfig() config { + return config{ + MaxWorkers: 1, + Poll: true, + PollInterval: 5 * time.Minute, + BucketTimeOut: 120 * time.Second, + ParseJSON: false, + } +} diff --git a/x-pack/filebeat/input/gcs/input.go b/x-pack/filebeat/input/gcs/input.go index cc0e9ad74bbb..33e46d034d76 100644 --- a/x-pack/filebeat/input/gcs/input.go +++ b/x-pack/filebeat/input/gcs/input.go @@ -50,7 +50,7 @@ func Plugin(log *logp.Logger, store cursor.StateStore) v2.Plugin { } func configure(cfg *conf.C) ([]cursor.Source, cursor.Input, error) { - config := config{} + config := defaultConfig() if err := cfg.Unpack(&config); err != nil { return nil, nil, err } @@ -78,44 +78,22 @@ func configure(cfg *conf.C) ([]cursor.Source, cursor.Input, error) { return sources, &gcsInput{config: config}, nil } -// tryOverrideOrDefault, overrides global values with local -// bucket level values if present. If both global & local values -// are absent, assigns default values +// tryOverrideOrDefault, overrides the bucket level values with global values if the bucket fields are not set func tryOverrideOrDefault(cfg config, b bucket) bucket { if b.MaxWorkers == nil { - maxWorkers := 1 - if cfg.MaxWorkers != nil { - maxWorkers = *cfg.MaxWorkers - } - b.MaxWorkers = &maxWorkers + b.MaxWorkers = &cfg.MaxWorkers } if b.Poll == nil { - var poll bool - if cfg.Poll != nil { - poll = *cfg.Poll - } - b.Poll = &poll + b.Poll = &cfg.Poll } if b.PollInterval == nil { - interval := time.Second * 300 - if cfg.PollInterval != nil { - interval = *cfg.PollInterval - } - b.PollInterval = &interval + b.PollInterval = &cfg.PollInterval } if b.ParseJSON == nil { - parse := false - if cfg.ParseJSON != nil { - parse = *cfg.ParseJSON - } - b.ParseJSON = &parse + b.ParseJSON = &cfg.ParseJSON } if b.BucketTimeOut == nil { - timeOut := time.Second * 50 - if cfg.BucketTimeOut != nil { - timeOut = *cfg.BucketTimeOut - } - b.BucketTimeOut = &timeOut + b.BucketTimeOut = &cfg.BucketTimeOut } if b.TimeStampEpoch == nil { b.TimeStampEpoch = cfg.TimeStampEpoch @@ -173,11 +151,12 @@ func (input *gcsInput) Run(inputCtx v2.Context, src cursor.Source, cancel() }() - client, err := fetchStorageClient(ctx, input.config, log) + client, err := fetchStorageClient(ctx, input.config) if err != nil { metrics.errorsTotal.Inc() return err } + bucket := client.Bucket(currentSource.BucketName).Retryer( // Use WithBackoff to change the timing of the exponential backoff. storage.WithBackoff(gax.Backoff{ diff --git a/x-pack/filebeat/input/gcs/input_stateless.go b/x-pack/filebeat/input/gcs/input_stateless.go index f56f7f35bc55..c0038bf31dce 100644 --- a/x-pack/filebeat/input/gcs/input_stateless.go +++ b/x-pack/filebeat/input/gcs/input_stateless.go @@ -88,7 +88,6 @@ func (in *statelessInput) Run(inputCtx v2.Context, publisher stateless.Publisher // Since we are only reading, the operation is always idempotent storage.WithPolicy(storage.RetryAlways), ) - scheduler := newScheduler(pub, bkt, currentSource, &in.config, st, metrics, log) // allows multiple containers to be scheduled concurrently while testing // the stateless input is triggered only while testing and till now it did not mimic diff --git a/x-pack/filebeat/input/gcs/input_test.go b/x-pack/filebeat/input/gcs/input_test.go index 8accb774f384..5595622c93e5 100644 --- a/x-pack/filebeat/input/gcs/input_test.go +++ b/x-pack/filebeat/input/gcs/input_test.go @@ -535,7 +535,7 @@ func Test_StorageClient(t *testing.T) { client, _ := storage.NewClient(context.Background(), option.WithEndpoint(serv.URL), option.WithoutAuthentication(), option.WithHTTPClient(&httpclient)) cfg := conf.MustNewConfigFrom(tt.baseConfig) - conf := config{} + conf := defaultConfig() err := cfg.Unpack(&conf) if err != nil { assert.EqualError(t, err, fmt.Sprint(tt.isError)) @@ -558,8 +558,8 @@ func Test_StorageClient(t *testing.T) { }) var timeout *time.Timer - if conf.PollInterval != nil { - timeout = time.NewTimer(1*time.Second + *conf.PollInterval) + if conf.PollInterval != 0 { + timeout = time.NewTimer(1*time.Second + conf.PollInterval) } else { timeout = time.NewTimer(5 * time.Second) } From 8e20316b921a5c8117421de50ed15212184b9f12 Mon Sep 17 00:00:00 2001 From: Anderson Queiroz Date: Tue, 3 Dec 2024 13:50:45 +0100 Subject: [PATCH 07/48] filestream: require unique input id on filebeat startup (#41731) During startup filebeat now validates the filestream inputs and fails to start if there are with duplicated IDs. Duplicated IDs might cause data duplication therefore now it's mandatory to have unique for each filestream input. Disruptive User Impact Impact: Users who have not configured unique IDs for their filestream inputs will need to update their configurations to include unique IDs for each input. Failure to do so will prevent Filebeat from starting. Previously: Filebeat would only log an error if filestream would find inputs with duplicated IDs, potentially leading to data duplication. Now: Filebeat will fail to start if any filestream input has a duplicated ID. --- CHANGELOG.next.asciidoc | 2 +- filebeat/beater/filebeat.go | 6 + filebeat/input/filestream/config.go | 59 ++++++ filebeat/input/filestream/config_test.go | 190 ++++++++++++++++++ filebeat/tests/integration/filestream_test.go | 166 +++++++++++++++ 5 files changed, 422 insertions(+), 1 deletion(-) diff --git a/CHANGELOG.next.asciidoc b/CHANGELOG.next.asciidoc index 7b7a351e2027..f95aebc42c54 100644 --- a/CHANGELOG.next.asciidoc +++ b/CHANGELOG.next.asciidoc @@ -50,8 +50,8 @@ https://github.com/elastic/beats/compare/v8.8.1\...main[Check the HEAD diff] - Remove deprecated awscloudwatch field from Filebeat. {pull}41089[41089] - The performance of ingesting SQS data with the S3 input has improved by up to 60x for queues with many small events. `max_number_of_messages` config for SQS mode is now ignored, as the new design no longer needs a manual cap on messages. Instead, use `number_of_workers` to scale ingestion rate in both S3 and SQS modes. The increased efficiency may increase network bandwidth consumption, which can be throttled by lowering `number_of_workers`. It may also increase number of events stored in memory, which can be throttled by lowering the configured size of the internal queue. {pull}40699[40699] - Fixes filestream logging the error "filestream input with ID 'ID' already exists, this will lead to data duplication[...]" on Kubernetes when using autodiscover. {pull}41585[41585] - - Add kafka compression support for ZSTD. +- Filebeat fails to start if there is any input with a duplicated ID. It logs the duplicated IDs and the offending inputs configurations. {pull}41731[41731] *Heartbeat* diff --git a/filebeat/beater/filebeat.go b/filebeat/beater/filebeat.go index 815b6fabfde2..ceab21aa3590 100644 --- a/filebeat/beater/filebeat.go +++ b/filebeat/beater/filebeat.go @@ -32,6 +32,7 @@ import ( "github.com/elastic/beats/v7/filebeat/fileset" _ "github.com/elastic/beats/v7/filebeat/include" "github.com/elastic/beats/v7/filebeat/input" + "github.com/elastic/beats/v7/filebeat/input/filestream" "github.com/elastic/beats/v7/filebeat/input/filestream/takeover" v2 "github.com/elastic/beats/v7/filebeat/input/v2" "github.com/elastic/beats/v7/filebeat/input/v2/compat" @@ -291,6 +292,11 @@ func (fb *Filebeat) Run(b *beat.Beat) error { } defer stateStore.Close() + err = filestream.ValidateInputIDs(config.Inputs, logp.NewLogger("input.filestream")) + if err != nil { + logp.Err("invalid filestream configuration: %+v", err) + return err + } err = processLogInputTakeOver(stateStore, config) if err != nil { logp.Err("Failed to attempt filestream state take over: %+v", err) diff --git a/filebeat/input/filestream/config.go b/filebeat/input/filestream/config.go index 1cb8fa5da979..2860dd673c23 100644 --- a/filebeat/input/filestream/config.go +++ b/filebeat/input/filestream/config.go @@ -19,6 +19,7 @@ package filestream import ( "fmt" + "strings" "time" "github.com/dustin/go-humanize" @@ -27,6 +28,7 @@ import ( "github.com/elastic/beats/v7/libbeat/reader/parser" "github.com/elastic/beats/v7/libbeat/reader/readfile" conf "github.com/elastic/elastic-agent-libs/config" + "github.com/elastic/elastic-agent-libs/logp" ) // Config stores the options of a file stream. @@ -142,3 +144,60 @@ func (c *config) Validate() error { return nil } + +// ValidateInputIDs checks all filestream inputs to ensure all input IDs are +// unique. If there is a duplicated ID, it logs an error containing the offending +// input configurations and returns an error containing the duplicated IDs. +// A single empty ID is a valid ID as it's unique, however multiple empty IDs +// are not unique and are therefore are treated as any other duplicated ID. +func ValidateInputIDs(inputs []*conf.C, logger *logp.Logger) error { + duplicatedConfigs := make(map[string][]*conf.C) + var duplicates []string + for _, input := range inputs { + fsInput := struct { + ID string `config:"id"` + Type string `config:"type"` + }{} + err := input.Unpack(&fsInput) + if err != nil { + return fmt.Errorf("failed to unpack filestream input configuration: %w", err) + } + if fsInput.Type == "filestream" { + duplicatedConfigs[fsInput.ID] = append(duplicatedConfigs[fsInput.ID], input) + // we just need to collect the duplicated IDs once, therefore collect + // it only the first time we see a duplicated ID. + if len(duplicatedConfigs[fsInput.ID]) == 2 { + duplicates = append(duplicates, fsInput.ID) + } + } + } + + if len(duplicates) != 0 { + jsonDupCfg := collectOffendingInputs(duplicates, duplicatedConfigs) + logger.Errorw("filestream inputs with duplicated IDs", "inputs", jsonDupCfg) + var quotedDuplicates []string + for _, dup := range duplicates { + quotedDuplicates = append(quotedDuplicates, fmt.Sprintf("%q", dup)) + } + return fmt.Errorf("filestream inputs validation error: filestream inputs with duplicated IDs: %v", strings.Join(quotedDuplicates, ",")) + } + + return nil +} + +func collectOffendingInputs(duplicates []string, ids map[string][]*conf.C) []map[string]interface{} { + var cfgs []map[string]interface{} + + for _, id := range duplicates { + for _, dupcfgs := range ids[id] { + toJson := map[string]interface{}{} + err := dupcfgs.Unpack(&toJson) + if err != nil { + toJson[id] = fmt.Sprintf("failed to unpack config: %v", err) + } + cfgs = append(cfgs, toJson) + } + } + + return cfgs +} diff --git a/filebeat/input/filestream/config_test.go b/filebeat/input/filestream/config_test.go index 6cf045060c94..729b712d58ea 100644 --- a/filebeat/input/filestream/config_test.go +++ b/filebeat/input/filestream/config_test.go @@ -18,9 +18,16 @@ package filestream import ( + "encoding/json" + "strings" "testing" + "github.com/stretchr/testify/assert" "github.com/stretchr/testify/require" + "go.uber.org/zap/zaptest/observer" + + conf "github.com/elastic/elastic-agent-libs/config" + "github.com/elastic/elastic-agent-libs/logp" ) func TestConfigValidate(t *testing.T) { @@ -30,3 +37,186 @@ func TestConfigValidate(t *testing.T) { require.Error(t, err) }) } + +func TestValidateInputIDs(t *testing.T) { + tcs := []struct { + name string + cfg []string + assertErr func(t *testing.T, err error) + assertLogs func(t *testing.T, buff *observer.ObservedLogs) + }{ + { + name: "empty config", + cfg: []string{""}, + assertErr: func(t *testing.T, err error) { + assert.NoError(t, err, "empty config should not return an error") + }, + }, + { + name: "one empty ID is allowed", + cfg: []string{` +type: filestream +`, ` +type: filestream +id: some-id-1 +`, ` +type: filestream +id: some-id-2 +`, + }, + assertErr: func(t *testing.T, err error) { + assert.NoError(t, err, "one empty id is allowed") + }, + }, + { + name: "duplicated empty ID", + cfg: []string{` +type: filestream +paths: + - "/tmp/empty-1" +`, ` +type: filestream +paths: + - "/tmp/empty-2" +`, ` +type: filestream +id: unique-id-1 +`, ` +type: filestream +id: unique-id-2 +`, ` +type: filestream +id: unique-ID +`, + }, + assertErr: func(t *testing.T, err error) { + assert.ErrorContains(t, err, `filestream inputs with duplicated IDs: ""`) + + }, + assertLogs: func(t *testing.T, obs *observer.ObservedLogs) { + want := `[{"paths":["/tmp/empty-1"],"type":"filestream"},{"paths":["/tmp/empty-2"],"type":"filestream"}]` + + logs := obs.TakeAll() + require.Len(t, logs, 1, "there should be only one log entry") + + got, err := json.Marshal(logs[0].ContextMap()["inputs"]) + require.NoError(t, err, "could not marshal duplicated IDs inputs") + assert.Equal(t, want, string(got)) + }, + }, { + name: "duplicated IDs", + cfg: []string{` +type: filestream +id: duplicated-id-1 +`, ` +type: filestream +id: duplicated-id-1 +`, ` +type: filestream +id: duplicated-id-2 +`, ` +type: filestream +id: duplicated-id-2 +`, ` +type: filestream +id: duplicated-id-2 +`, ` +type: filestream +id: unique-ID +`, + }, + assertErr: func(t *testing.T, err error) { + assert.ErrorContains(t, err, "filestream inputs with duplicated IDs") + assert.ErrorContains(t, err, "duplicated-id-1") + assert.ErrorContains(t, err, "duplicated-id-2") + assert.Equal(t, strings.Count(err.Error(), "duplicated-id-1"), 1, "each IDs should appear only once") + assert.Equal(t, strings.Count(err.Error(), "duplicated-id-2"), 1, "each IDs should appear only once") + + }, + assertLogs: func(t *testing.T, obs *observer.ObservedLogs) { + want := `[{"id":"duplicated-id-1","type":"filestream"},{"id":"duplicated-id-1","type":"filestream"},{"id":"duplicated-id-2","type":"filestream"},{"id":"duplicated-id-2","type":"filestream"},{"id":"duplicated-id-2","type":"filestream"}]` + + logs := obs.TakeAll() + require.Len(t, logs, 1, "there should be only one log entry") + + got, err := json.Marshal(logs[0].ContextMap()["inputs"]) + require.NoError(t, err, "could not marshal duplicated IDs inputs") + assert.Equal(t, want, string(got)) + }, + }, + { + name: "duplicated IDs and empty ID", + cfg: []string{` +type: filestream +`, ` +type: filestream +`, ` +type: filestream +id: duplicated-id-1 +`, ` +type: filestream +id: duplicated-id-1 +`, ` +type: filestream +id: duplicated-id-2 +`, ` +type: filestream +id: duplicated-id-2 +`, ` +type: filestream +id: unique-ID +`, + }, + assertErr: func(t *testing.T, err error) { + assert.ErrorContains(t, err, "filestream inputs with duplicated IDs") + }, + assertLogs: func(t *testing.T, obs *observer.ObservedLogs) { + want := `[{"type":"filestream"},{"type":"filestream"},{"id":"duplicated-id-1","type":"filestream"},{"id":"duplicated-id-1","type":"filestream"},{"id":"duplicated-id-2","type":"filestream"},{"id":"duplicated-id-2","type":"filestream"}]` + + logs := obs.TakeAll() + require.Len(t, logs, 1, "there should be only one log entry") + + got, err := json.Marshal(logs[0].ContextMap()["inputs"]) + require.NoError(t, err, "could not marshal duplicated IDs inputs") + assert.Equal(t, want, string(got)) + + }, + }, + { + name: "only unique IDs", + cfg: []string{` +type: filestream +id: unique-id-1 +`, ` +type: filestream +id: unique-id-2 +`, ` +type: filestream +id: unique-id-3 +`, + }, + assertErr: func(t *testing.T, err error) { + assert.NoError(t, err, "only unique IDs should not return an error") + }, + }, + } + + for _, tc := range tcs { + t.Run(tc.name, func(t *testing.T) { + var inputs []*conf.C + for _, c := range tc.cfg { + cfg, err := conf.NewConfigFrom(c) + require.NoError(t, err, "could not create input configuration") + inputs = append(inputs, cfg) + } + err := logp.DevelopmentSetup(logp.ToObserverOutput()) + require.NoError(t, err, "could not setup log for development") + + err = ValidateInputIDs(inputs, logp.L()) + tc.assertErr(t, err) + if tc.assertLogs != nil { + tc.assertLogs(t, logp.ObserverLogs()) + } + }) + } +} diff --git a/filebeat/tests/integration/filestream_test.go b/filebeat/tests/integration/filestream_test.go index 3ddb04a2c20c..45cf99fbfb61 100644 --- a/filebeat/tests/integration/filestream_test.go +++ b/filebeat/tests/integration/filestream_test.go @@ -26,6 +26,9 @@ import ( "testing" "time" + "github.com/stretchr/testify/assert" + "github.com/stretchr/testify/require" + "github.com/elastic/beats/v7/libbeat/tests/integration" ) @@ -105,3 +108,166 @@ func TestFilestreamCleanInactive(t *testing.T) { registryFile := filepath.Join(filebeat.TempDir(), "data", "registry", "filebeat", "log.json") filebeat.WaitFileContains(registryFile, `"op":"remove"`, time.Second) } + +func TestFilestreamValidationPreventsFilebeatStart(t *testing.T) { + duplicatedIDs := ` +filebeat.inputs: + - type: filestream + id: duplicated-id-1 + enabled: true + paths: + - /tmp/*.log + - type: filestream + id: duplicated-id-1 + enabled: true + paths: + - /var/log/*.log + +output.discard.enabled: true +logging: + level: debug + metrics: + enabled: false +` + emptyID := ` +filebeat.inputs: + - type: filestream + enabled: true + paths: + - /tmp/*.log + - type: filestream + enabled: true + paths: + - /var/log/*.log + +output.discard.enabled: true +logging: + level: debug + metrics: + enabled: false +` + multipleDuplicatedIDs := ` +filebeat.inputs: + - type: filestream + enabled: true + paths: + - /tmp/*.log + - type: filestream + enabled: true + paths: + - /var/log/*.log + + - type: filestream + id: duplicated-id-1 + enabled: true + paths: + - /tmp/duplicated-id-1.log + - type: filestream + id: duplicated-id-1 + enabled: true + paths: + - /tmp/duplicated-id-1-2.log + + + - type: filestream + id: unique-id-1 + enabled: true + paths: + - /tmp/unique-id-1.log + - type: filestream + id: unique-id-2 + enabled: true + paths: + - /var/log/unique-id-2.log + +output.discard.enabled: true +logging: + level: debug + metrics: + enabled: false +` + tcs := []struct { + name string + cfg string + }{ + { + name: "duplicated IDs", + cfg: duplicatedIDs, + }, + { + name: "duplicated empty ID", + cfg: emptyID, + }, + { + name: "two inputs without ID and duplicated IDs", + cfg: multipleDuplicatedIDs, + }, + } + + for _, tc := range tcs { + t.Run(tc.name, func(t *testing.T) { + filebeat := integration.NewBeat( + t, + "filebeat", + "../../filebeat.test", + ) + + // Write configuration file and start Filebeat + filebeat.WriteConfigFile(tc.cfg) + filebeat.Start() + + // Wait for error log + filebeat.WaitForLogs( + "filestream inputs validation error", + 10*time.Second, + "Filebeat did not log a filestream input validation error") + + proc, err := filebeat.Process.Wait() + require.NoError(t, err, "filebeat process.Wait returned an error") + assert.False(t, proc.Success(), "filebeat should have failed to start") + + }) + } +} + +func TestFilestreamValidationSucceeds(t *testing.T) { + cfg := ` +filebeat.inputs: + - type: filestream + enabled: true + paths: + - /var/log/*.log + + - type: filestream + id: unique-id-1 + enabled: true + paths: + - /tmp/unique-id-1.log + - type: filestream + id: unique-id-2 + enabled: true + paths: + - /var/log/unique-id-2.log + +output.discard.enabled: true +logging: + level: debug + metrics: + enabled: false +` + filebeat := integration.NewBeat( + t, + "filebeat", + "../../filebeat.test", + ) + + // Write configuration file and start Filebeat + filebeat.WriteConfigFile(cfg) + filebeat.Start() + + // Wait for error log + filebeat.WaitForLogs( + "Input 'filestream' starting", + 10*time.Second, + "Filebeat did log a validation error") +} From a1acad54fa99ee884cb3576ea74f494dd1a63da6 Mon Sep 17 00:00:00 2001 From: stefans-elastic Date: Tue, 3 Dec 2024 20:28:42 +0200 Subject: [PATCH 08/48] [xpack][metricbeats][gcp] don't skip first value in histogram calculations (#41822) * [xpack][metricbeats][gcp] don't skip first value in histogram calculations * update changelog * update PR id in changelog * update data_topic.json * update data_topic.json * fix integer overflow --------- Co-authored-by: Ishleen Kaur <102962586+ishleenk17@users.noreply.github.com> --- CHANGELOG.next.asciidoc | 1 + x-pack/metricbeat/module/gcp/distribution.go | 14 +-- .../module/gcp/distribution_test.go | 12 +- .../module/gcp/pubsub/_meta/data_topic.json | 111 ++++++++++++++++-- 4 files changed, 112 insertions(+), 26 deletions(-) diff --git a/CHANGELOG.next.asciidoc b/CHANGELOG.next.asciidoc index f95aebc42c54..2c364a3715f4 100644 --- a/CHANGELOG.next.asciidoc +++ b/CHANGELOG.next.asciidoc @@ -217,6 +217,7 @@ https://github.com/elastic/beats/compare/v8.8.1\...main[Check the HEAD diff] - Fix Kubernetes metadata sometimes not being present after startup {pull}41216[41216] - Do not report non-existant 0 values for RSS metrics in docker/memory {pull}41449[41449] - Log Cisco Meraki `getDevicePerformanceScores` errors without stopping metrics collection. {pull}41622[41622] +- Don't skip first bucket value in GCP metrics metricset for distribution type metrics {pull}41822[41822] *Osquerybeat* diff --git a/x-pack/metricbeat/module/gcp/distribution.go b/x-pack/metricbeat/module/gcp/distribution.go index aae21e1d58e5..f77b3afc7112 100644 --- a/x-pack/metricbeat/module/gcp/distribution.go +++ b/x-pack/metricbeat/module/gcp/distribution.go @@ -53,7 +53,7 @@ func calcLinearUpperBound(bucket *distribution.Distribution_BucketOptions_Linear return bucket.Offset + (bucket.Width * float64(i)) } -func createHistogram(values []float64, counts []uint64) mapstr.M { +func createHistogram(values []float64, counts []int64) mapstr.M { return mapstr.M{ "values": values, "counts": counts, @@ -62,11 +62,11 @@ func createHistogram(values []float64, counts []uint64) mapstr.M { func DistributionHistogramToES(d *distribution.Distribution) mapstr.M { if !containsHistogram(d) { - return createHistogram([]float64{}, []uint64{}) + return createHistogram([]float64{}, []int64{}) } values := make([]float64, 0, len(d.BucketCounts)) - counts := make([]uint64, 0, len(d.BucketCounts)) + counts := make([]int64, 0, len(d.BucketCounts)) switch { case d.BucketOptions.GetExplicitBuckets() != nil: @@ -79,19 +79,17 @@ func DistributionHistogramToES(d *distribution.Distribution) mapstr.M { bucket := d.BucketOptions.GetExponentialBuckets() for i := range d.BucketCounts { - values = append(values, calcExponentialUpperBound(bucket, i+1)) + values = append(values, calcExponentialUpperBound(bucket, i)) } case d.BucketOptions.GetLinearBuckets() != nil: bucket := d.BucketOptions.GetLinearBuckets() for i := range d.BucketCounts { - values = append(values, calcLinearUpperBound(bucket, i+1)) + values = append(values, calcLinearUpperBound(bucket, i)) } } - for i := range d.BucketCounts { - counts = append(counts, uint64(d.BucketCounts[i])) - } + counts = append(counts, d.BucketCounts...) return createHistogram(values, counts) } diff --git a/x-pack/metricbeat/module/gcp/distribution_test.go b/x-pack/metricbeat/module/gcp/distribution_test.go index e2f582653beb..3838a9e9dd3a 100644 --- a/x-pack/metricbeat/module/gcp/distribution_test.go +++ b/x-pack/metricbeat/module/gcp/distribution_test.go @@ -40,7 +40,7 @@ func TestDistributionHistogramToES(t *testing.T) { }, }, expected: mapstr.M{ - "counts": []uint64{0, 0, 0, 6, 1, 1}, + "counts": []int64{0, 0, 0, 6, 1, 1}, "values": []float64{0, 1, 2, 5, 10, 20}, }, }, @@ -63,8 +63,8 @@ func TestDistributionHistogramToES(t *testing.T) { }, }, expected: mapstr.M{ - "counts": []uint64{0, 0, 3, 1}, - "values": []float64{6, 12, 24, 48}, + "counts": []int64{0, 0, 3, 1}, + "values": []float64{3, 6, 12, 24}, }, }, }, @@ -86,8 +86,8 @@ func TestDistributionHistogramToES(t *testing.T) { }, }, expected: mapstr.M{ - "counts": []uint64{0, 1, 2, 0}, - "values": []float64{20, 35, 50, 65}, + "counts": []int64{0, 1, 2, 0}, + "values": []float64{5, 20, 35, 50}, }, }, }, @@ -107,7 +107,7 @@ func TestDistributionHistogramToES(t *testing.T) { }, }, expected: mapstr.M{ - "counts": []uint64{}, + "counts": []int64{}, "values": []float64{}, }, }, diff --git a/x-pack/metricbeat/module/gcp/pubsub/_meta/data_topic.json b/x-pack/metricbeat/module/gcp/pubsub/_meta/data_topic.json index 1453f9f379c7..cb6585606dfd 100644 --- a/x-pack/metricbeat/module/gcp/pubsub/_meta/data_topic.json +++ b/x-pack/metricbeat/module/gcp/pubsub/_meta/data_topic.json @@ -12,25 +12,112 @@ "module": "gcp" }, "gcp": { - "labels": { - "resource": { - "topic_id": "test-ks" - } - }, "pubsub": { "topic": { "message_sizes": { - "bucket_options": { - "Options": { - "ExponentialBuckets": { - "num_finite_buckets": 16, - "growth_factor": 4, - "scale": 1 - } + "bytes": { + "histogram": { + "values": [ + 1, + 1.2, + 1.44, + 1.728, + 2.0736, + 2.48832, + 2.9859839999999997, + 3.5831807999999996, + 4.299816959999999, + 5.159780351999999, + 6.191736422399999, + 7.430083706879999, + 8.916100448255998, + 10.699320537907198, + 12.839184645488636, + 15.407021574586365, + 18.488425889503635, + 22.18611106740436, + 26.623333280885234, + 31.94799993706228, + 38.33759992447474, + 46.00511990936968, + 55.20614389124361, + 66.24737266949234, + 79.4968472033908, + 95.39621664406897, + 114.47545997288276, + 137.3705519674593, + 164.84466236095116, + 197.8135948331414, + 237.37631379976966, + 284.8515765597236, + 341.82189187166824, + 410.18627024600187, + 492.22352429520225, + 590.6682291542427, + 708.8018749850912, + 850.5622499821095, + 1020.6746999785313, + 1224.8096399742376, + 1469.771567969085, + 1763.725881562902, + 2116.4710578754825, + 2539.7652694505787 + ], + "counts": [ + 0, + 0, + 0, + 0, + 0, + 0, + 0, + 0, + 0, + 0, + 0, + 0, + 0, + 0, + 0, + 0, + 0, + 0, + 0, + 0, + 0, + 0, + 0, + 0, + 0, + 0, + 0, + 0, + 0, + 0, + 0, + 0, + 0, + 0, + 0, + 0, + 0, + 0, + 0, + 0, + 1, + 10, + 3, + 2 + ] } } } } + }, + "labels": { + "resource": { + "topic_id": "test-topic" + } } }, "metricset": { From 9045642cb4594c6343f2abd5cb613f9c674593c1 Mon Sep 17 00:00:00 2001 From: kruskall <99559985+kruskall@users.noreply.github.com> Date: Tue, 3 Dec 2024 20:29:08 +0100 Subject: [PATCH 09/48] test: bind mount gomodcache to cache go dependencies (#41846) * test: bind mount gomodcache to cache go dependencies try to speed up ci jobs integration tests * test(metricbeat): do not make gomodcache readonly * lint: replace ioutil usage * test: fail on empty gomodcache * test: rework cache bind approach instead of binding the volume on each dockerfile, run the container with the proper volume arg * test: bind gomodcache in kubernetes runner * test: sync the gomodcache with rsync and fix linter issues can't really bind using hostpath in k8s * test: rework bind approach with k8s runner since it's a local cluster, use kind to bind the hostpath to the node then bind the node path to the container path * lint: remove unused imports * lint: fix linter issues --- dev-tools/mage/integtest_docker.go | 15 +++---- dev-tools/mage/kubernetes/kind.go | 31 +++++++++++--- dev-tools/mage/kubernetes/kuberemote.go | 55 +++++++++++++++---------- 3 files changed, 65 insertions(+), 36 deletions(-) diff --git a/dev-tools/mage/integtest_docker.go b/dev-tools/mage/integtest_docker.go index 8c5fb6d3603f..ea29d993b272 100644 --- a/dev-tools/mage/integtest_docker.go +++ b/dev-tools/mage/integtest_docker.go @@ -22,7 +22,6 @@ import ( "fmt" "go/build" "io" - "io/ioutil" "os" "path" "path/filepath" @@ -99,11 +98,9 @@ func (d *DockerIntegrationTester) Test(dir string, mageTarget string, env map[st if err != nil { return err } - dockerRepoRoot := filepath.Join("/go/src", repo.CanonicalRootImportPath) - dockerGoCache := filepath.Join(dockerRepoRoot, "build/docker-gocache") magePath := filepath.Join("/go/src", repo.CanonicalRootImportPath, repo.SubDir, "build/mage-linux-"+GOARCH) - goPkgCache := filepath.Join(filepath.SplitList(build.Default.GOPATH)[0], "pkg/mod/cache/download") - dockerGoPkgCache := "/gocache" + goPkgCache := filepath.Join(filepath.SplitList(build.Default.GOPATH)[0], "pkg/mod") + dockerGoPkgCache := "/go/pkg/mod" // Execute the inside of docker-compose. args := []string{"-p", DockerComposeProjectName(), "run", @@ -114,10 +111,8 @@ func (d *DockerIntegrationTester) Test(dir string, mageTarget string, env map[st // compose.EnsureUp needs to know the environment type. "-e", "STACK_ENVIRONMENT=" + StackEnvironment, "-e", "TESTING_ENVIRONMENT=" + StackEnvironment, - "-e", "GOCACHE=" + dockerGoCache, // Use the host machine's pkg cache to minimize external downloads. - "-v", goPkgCache + ":" + dockerGoPkgCache + ":ro", - "-e", "GOPROXY=file://" + dockerGoPkgCache + ",direct", + "-v", goPkgCache + ":" + dockerGoPkgCache, } args, err = addUidGidEnvArgs(args) if err != nil { @@ -356,7 +351,7 @@ func StartIntegTestContainers() error { func StopIntegTestContainers() error { // Docker-compose rm is noisy. So only pass through stderr when in verbose. - out := ioutil.Discard + out := io.Discard if mg.Verbose() { out = os.Stderr } @@ -368,7 +363,7 @@ func StopIntegTestContainers() error { _, err = sh.Exec( composeEnv, - ioutil.Discard, + io.Discard, out, "docker-compose", "-p", DockerComposeProjectName(), diff --git a/dev-tools/mage/kubernetes/kind.go b/dev-tools/mage/kubernetes/kind.go index 133f305fedd2..43ef37e10a4a 100644 --- a/dev-tools/mage/kubernetes/kind.go +++ b/dev-tools/mage/kubernetes/kind.go @@ -19,7 +19,8 @@ package kubernetes import ( "fmt" - "io/ioutil" + "go/build" + "io" "os" "os/exec" "path/filepath" @@ -66,8 +67,8 @@ func (m *KindIntegrationTestStep) Setup(env map[string]string) error { } clusterName := kubernetesClusterName() - stdOut := ioutil.Discard - stdErr := ioutil.Discard + stdOut := io.Discard + stdErr := io.Discard if mg.Verbose() { stdOut = os.Stdout stdErr = os.Stderr @@ -86,9 +87,29 @@ func (m *KindIntegrationTestStep) Setup(env map[string]string) error { return err } + cfg, err := os.CreateTemp("", "kind-") + if err != nil { + return err + } + if _, err := cfg.WriteString(fmt.Sprintf(` +apiVersion: kind.x-k8s.io/v1alpha4 +kind: Cluster +nodes: + - role: control-plane + extraMounts: + - hostPath: %s + containerPath: /go/pkg/mod +`, filepath.Join(build.Default.GOPATH, "pkg", "mod"))); err != nil { + return err + } + if err := cfg.Close(); err != nil { + return err + } + args := []string{ "create", "cluster", + "--config", cfg.Name(), "--name", clusterName, "--kubeconfig", kubeConfig, "--wait", @@ -116,8 +137,8 @@ func (m *KindIntegrationTestStep) Setup(env map[string]string) error { // Teardown destroys the kubernetes cluster. func (m *KindIntegrationTestStep) Teardown(env map[string]string) error { - stdOut := ioutil.Discard - stdErr := ioutil.Discard + stdOut := io.Discard + stdErr := io.Discard if mg.Verbose() { stdOut = os.Stdout stdErr = os.Stderr diff --git a/dev-tools/mage/kubernetes/kuberemote.go b/dev-tools/mage/kubernetes/kuberemote.go index e3062f00d1ad..fb028dc94db3 100644 --- a/dev-tools/mage/kubernetes/kuberemote.go +++ b/dev-tools/mage/kubernetes/kuberemote.go @@ -23,14 +23,14 @@ import ( "crypto/rand" "crypto/rsa" "crypto/x509" - "encoding/hex" "encoding/pem" "fmt" "io" - "io/ioutil" + "log" "net" "net/http" "net/url" + "os" "os/exec" "strings" "time" @@ -127,11 +127,17 @@ func (r *KubeRemote) Run(env map[string]string, stdout io.Writer, stderr io.Writ if err != nil { return err } - go f.ForwardPorts() + go func() { + if err := f.ForwardPorts(); err != nil { + log.Printf("forward port error: %v\n", err) + } + }() <-readyChannel // perform the rsync - r.rsync(randomPort, stderr, stderr) + if err := r.rsync(randomPort, stderr, stderr, r.syncDir, r.destDir); err != nil { + return fmt.Errorf("rsync failed: %w", err) + } // stop port forwarding close(stopChannel) @@ -258,14 +264,14 @@ func (r *KubeRemote) portForward(ports []string, stopChannel, readyChannel chan } path := fmt.Sprintf("/api/v1/namespaces/%s/pods/%s/portforward", r.namespace, r.name) - hostIP := strings.TrimLeft(r.cfg.Host, "https://") + hostIP := strings.TrimPrefix(r.cfg.Host, "https://") serverURL := url.URL{Scheme: "https", Path: path, Host: hostIP} dialer := spdy.NewDialer(upgrader, &http.Client{Transport: roundTripper}, http.MethodPost, &serverURL) return portforward.New(dialer, ports, stopChannel, readyChannel, stdout, stderr) } // rsync performs the rsync of sync directory to destination directory inside of the pod. -func (r *KubeRemote) rsync(port uint16, stdout, stderr io.Writer) error { +func (r *KubeRemote) rsync(port uint16, stdout, stderr io.Writer, src string, dst string) error { privateKeyFile, err := createTempFile(r.privateKey) if err != nil { return err @@ -274,8 +280,8 @@ func (r *KubeRemote) rsync(port uint16, stdout, stderr io.Writer) error { rsh := fmt.Sprintf("ssh -o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null -o LogLevel=ERROR -p %d -i %s", port, privateKeyFile) args := []string{ "--rsh", rsh, - "-a", fmt.Sprintf("%s/", r.syncDir), - fmt.Sprintf("root@localhost:%s", r.destDir), + "-a", fmt.Sprintf("%s/", src), + fmt.Sprintf("root@localhost:%s", dst), } cmd := exec.Command("rsync", args...) cmd.Stdout = stdout @@ -491,6 +497,10 @@ func createPodManifest(name string, image string, env map[string]string, cmd []s Name: "destdir", MountPath: destDir, }, + { + Name: "gomodcache", + MountPath: "/go/pkg/mod", + }, }, }, }, @@ -510,6 +520,14 @@ func createPodManifest(name string, image string, env map[string]string, cmd []s EmptyDir: &apiv1.EmptyDirVolumeSource{}, }, }, + { + Name: "gomodcache", + VolumeSource: apiv1.VolumeSource{ + HostPath: &apiv1.HostPathVolumeSource{ + Path: "/go/pkg/mod", + }, + }, + }, }, }, } @@ -542,7 +560,7 @@ func isInitContainersReady(pod *apiv1.Pod) bool { } func isScheduled(pod *apiv1.Pod) bool { - if &pod.Status != nil && len(pod.Status.Conditions) > 0 { + if len(pod.Status.Conditions) > 0 { for _, condition := range pod.Status.Conditions { if condition.Type == apiv1.PodScheduled && condition.Status == apiv1.ConditionTrue { @@ -554,18 +572,15 @@ func isScheduled(pod *apiv1.Pod) bool { } func isInitContainersRunning(pod *apiv1.Pod) bool { - if &pod.Status != nil { - if len(pod.Spec.InitContainers) != len(pod.Status.InitContainerStatuses) { + if len(pod.Spec.InitContainers) != len(pod.Status.InitContainerStatuses) { + return false + } + for _, status := range pod.Status.InitContainerStatuses { + if status.State.Running == nil { return false } - for _, status := range pod.Status.InitContainerStatuses { - if status.State.Running == nil { - return false - } - } - return true } - return false + return true } func containerRunning(containerName string) func(watch.Event) (bool, error) { @@ -620,9 +635,7 @@ func podDone(event watch.Event) (bool, error) { } func createTempFile(content []byte) (string, error) { - randBytes := make([]byte, 16) - rand.Read(randBytes) - tmpfile, err := ioutil.TempFile("", hex.EncodeToString(randBytes)) + tmpfile, err := os.CreateTemp("", "kuberemote-") if err != nil { return "", err } From ab0f3c836e4578b10fa59a0423fdc9ef83f89d66 Mon Sep 17 00:00:00 2001 From: Lee E Hinman <57081003+leehinman@users.noreply.github.com> Date: Tue, 3 Dec 2024 13:57:32 -0600 Subject: [PATCH 10/48] don't panic loading twice (#41857) --- CHANGELOG.next.asciidoc | 1 + libbeat/processors/namespace.go | 11 ++++++++--- libbeat/processors/namespace_test.go | 2 +- 3 files changed, 10 insertions(+), 4 deletions(-) diff --git a/CHANGELOG.next.asciidoc b/CHANGELOG.next.asciidoc index 2c364a3715f4..25ccd945571e 100644 --- a/CHANGELOG.next.asciidoc +++ b/CHANGELOG.next.asciidoc @@ -116,6 +116,7 @@ https://github.com/elastic/beats/compare/v8.8.1\...main[Check the HEAD diff] - Add `translate_ldap_attribute` processor. {pull}41472[41472] - Remove unnecessary debug logs during idle connection teardown {issue}40824[40824] - Fix incorrect cloud provider identification in add_cloud_metadata processor using provider priority mechanism {pull}41636[41636] +- Prevent panic if libbeat processors are loaded more than once. {issue}41475[41475] {pull}41857[51857] *Auditbeat* diff --git a/libbeat/processors/namespace.go b/libbeat/processors/namespace.go index 0ccf1deda458..5d015b16bcf1 100644 --- a/libbeat/processors/namespace.go +++ b/libbeat/processors/namespace.go @@ -38,6 +38,11 @@ type pluginer interface { Plugin() Constructor } +var ( + ErrExistsAlready error = errors.New("exists already") + ErrPluginAlreadyRegistered error = errors.New("non-namespace plugin already registered") +) + func NewNamespace() *Namespace { return &Namespace{ reg: map[string]pluginer{}, @@ -47,7 +52,7 @@ func NewNamespace() *Namespace { func (ns *Namespace) Register(name string, factory Constructor) error { p := plugin{NewConditional(factory)} names := strings.Split(name, ".") - if err := ns.add(names, p); err != nil { + if err := ns.add(names, p); err != nil && !errors.Is(err, ErrExistsAlready) && !errors.Is(err, ErrPluginAlreadyRegistered) { return fmt.Errorf("plugin %s registration fail %w", name, err) } return nil @@ -59,7 +64,7 @@ func (ns *Namespace) add(names []string, p pluginer) error { // register plugin if intermediate node in path being processed if len(names) == 1 { if _, found := ns.reg[name]; found { - return fmt.Errorf("%v exists already", name) + return fmt.Errorf("%s %w", name, ErrExistsAlready) } ns.reg[name] = p @@ -71,7 +76,7 @@ func (ns *Namespace) add(names []string, p pluginer) error { if found { ns, ok := tmp.(*Namespace) if !ok { - return errors.New("non-namespace plugin already registered") + return ErrPluginAlreadyRegistered } return ns.add(names[1:], p) } diff --git a/libbeat/processors/namespace_test.go b/libbeat/processors/namespace_test.go index 07c62328c2c1..221cee9b2e37 100644 --- a/libbeat/processors/namespace_test.go +++ b/libbeat/processors/namespace_test.go @@ -65,7 +65,7 @@ func TestNamespaceRegisterFail(t *testing.T) { fatalError(t, err) err = ns.Register("test", newTestFilterRule) - assert.Error(t, err) + assert.NoError(t, err) } func TestNamespaceError(t *testing.T) { From 8b38b65ec4fb301c084b9a5741f3e7490c82b4b3 Mon Sep 17 00:00:00 2001 From: Christiano Haesbaert Date: Tue, 3 Dec 2024 21:20:13 +0100 Subject: [PATCH 11/48] helper/hasher general improvements (#41863) * Fix a TOCTOU by opening the file handle and then doing stat(), instead of doning stat() and then opening. * Make sure this is a regular file, otherwise you could trick auditbeat into hashing an infinite source like a pipe. * Allow for rate (but not file size) to be infinite, this is needed for an upcoming new backend for module/system/process. * Finally, fix error messages that show up on ECS, see below. before: ``` failed to hash executable /d/e/beats/x-pack/auditbeat/auditbeat for PID 50751: failed to hash file /d/e/beats/x-pack/auditbeat/auditbeat: hasher: file size 143673152 exceeds max file size ``` after: ``` failed to hash executable /d/e/beats/x-pack/auditbeat/auditbeat for PID 50804: size 143673152 exceeds max file size ``` --- CHANGELOG.next.asciidoc | 1 + auditbeat/helper/hasher/hasher.go | 43 +++++++++++++++++++++---------- 2 files changed, 30 insertions(+), 14 deletions(-) diff --git a/CHANGELOG.next.asciidoc b/CHANGELOG.next.asciidoc index 25ccd945571e..903da4c9fd45 100644 --- a/CHANGELOG.next.asciidoc +++ b/CHANGELOG.next.asciidoc @@ -123,6 +123,7 @@ https://github.com/elastic/beats/compare/v8.8.1\...main[Check the HEAD diff] - auditd: Request status from a separate socket to avoid data congestion {pull}41207[41207] - auditd: Use ECS `event.type: end` instead of `stop` for SERVICE_STOP, DAEMON_ABORT, and DAEMON_END messages. {pull}41558[41558] - auditd: Update syscall names for Linux 6.11. {pull}41558[41558] +- hasher: Geneneral improvements and fixes. {pull}41863[41863] *Filebeat* diff --git a/auditbeat/helper/hasher/hasher.go b/auditbeat/helper/hasher/hasher.go index d0612ab731df..4f97f5705a74 100644 --- a/auditbeat/helper/hasher/hasher.go +++ b/auditbeat/helper/hasher/hasher.go @@ -26,7 +26,6 @@ import ( "fmt" "hash" "io" - "os" "strings" "time" @@ -124,7 +123,7 @@ type FileTooLargeError struct { // Error returns the error message for FileTooLargeError. func (e FileTooLargeError) Error() string { - return fmt.Sprintf("hasher: file size %d exceeds max file size", e.fileSize) + return fmt.Sprintf("size %d exceeds max file size", e.fileSize) } // Config contains the configuration of a FileHasher. @@ -174,11 +173,19 @@ type FileHasher struct { // NewFileHasher creates a new FileHasher. func NewFileHasher(c Config, done <-chan struct{}) (*FileHasher, error) { + var limit rate.Limit + + if c.ScanRateBytesPerSec == 0 { + limit = rate.Inf + } else { + limit = rate.Limit(c.ScanRateBytesPerSec) + } + return &FileHasher{ config: c, limiter: rate.NewLimiter( - rate.Limit(c.ScanRateBytesPerSec), // Rate - int(c.MaxFileSizeBytes), // Burst + limit, // Rate + int(c.MaxFileSizeBytes), // Burst ), done: done, }, nil @@ -186,16 +193,26 @@ func NewFileHasher(c Config, done <-chan struct{}) (*FileHasher, error) { // HashFile hashes the contents of a file. func (hasher *FileHasher) HashFile(path string) (map[HashType]Digest, error) { - info, err := os.Stat(path) + f, err := file.ReadOpen(path) if err != nil { - return nil, fmt.Errorf("failed to stat file %v: %w", path, err) + return nil, fmt.Errorf("open: %w", err) + } + defer f.Close() + + info, err := f.Stat() + if err != nil { + return nil, fmt.Errorf("stat: %w", err) + } + if !info.Mode().IsRegular() { + return nil, fmt.Errorf("not a regular file") + } // Throttle reading and hashing rate. if len(hasher.config.HashTypes) > 0 { err = hasher.throttle(info.Size()) if err != nil { - return nil, fmt.Errorf("failed to hash file %v: %w", path, err) + return nil, err } } @@ -210,15 +227,9 @@ func (hasher *FileHasher) HashFile(path string) (map[HashType]Digest, error) { } if len(hashes) > 0 { - f, err := file.ReadOpen(path) - if err != nil { - return nil, fmt.Errorf("failed to open file for hashing: %w", err) - } - defer f.Close() - hashWriter := multiWriter(hashes) if _, err := io.Copy(hashWriter, f); err != nil { - return nil, fmt.Errorf("failed to calculate file hashes: %w", err) + return nil, err } nameToHash := make(map[HashType]Digest, len(hashes)) @@ -233,6 +244,10 @@ func (hasher *FileHasher) HashFile(path string) (map[HashType]Digest, error) { } func (hasher *FileHasher) throttle(fileSize int64) error { + // Burst is ignored if limit is infinite, so check it manually + if hasher.limiter.Limit() == rate.Inf && int(fileSize) > hasher.limiter.Burst() { + return FileTooLargeError{fileSize} + } reservation := hasher.limiter.ReserveN(time.Now(), int(fileSize)) if !reservation.OK() { // File is bigger than the max file size From 5a85598f4e4895c6ff1f0586d2a91230a4aba4e0 Mon Sep 17 00:00:00 2001 From: Christiano Haesbaert Date: Tue, 3 Dec 2024 21:21:27 +0100 Subject: [PATCH 12/48] auditbeat: split system process module (#41868) This splits the common module parts and the gosysinfo backend. Needed for an upcoming PR which adds a quark backend, so I'm splitting this earlier to make review easier. Only functional case for this PR is add missing `bucket.Close()` calls in New(). --- CHANGELOG.next.asciidoc | 1 + .../system/process/gosysinfo_provider.go | 461 ++++++++++++++++++ .../module/system/process/process.go | 459 +---------------- .../module/system/process/process_test.go | 7 +- 4 files changed, 485 insertions(+), 443 deletions(-) create mode 100644 x-pack/auditbeat/module/system/process/gosysinfo_provider.go diff --git a/CHANGELOG.next.asciidoc b/CHANGELOG.next.asciidoc index 903da4c9fd45..c9b8f120e540 100644 --- a/CHANGELOG.next.asciidoc +++ b/CHANGELOG.next.asciidoc @@ -264,6 +264,7 @@ https://github.com/elastic/beats/compare/v8.8.1\...main[Check the HEAD diff] - Add linux capabilities to processes in the system/process. {pull}37453[37453] - Add linux capabilities to processes in the system/process. {pull}37453[37453] - Add process.entity_id, process.group.name and process.group.id in add_process_metadata processor. Make fim module with kprobes backend to always add an appropriately configured add_process_metadata processor to enrich file events {pull}38776[38776] +- Split module/system/process into common and provider bits. {pull}41868[41868] *Auditbeat* diff --git a/x-pack/auditbeat/module/system/process/gosysinfo_provider.go b/x-pack/auditbeat/module/system/process/gosysinfo_provider.go new file mode 100644 index 000000000000..da82a2e18106 --- /dev/null +++ b/x-pack/auditbeat/module/system/process/gosysinfo_provider.go @@ -0,0 +1,461 @@ +// Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one +// or more contributor license agreements. Licensed under the Elastic License; +// you may not use this file except in compliance with the Elastic License. + +package process + +import ( + "fmt" + "os" + "os/user" + "runtime" + "strconv" + "time" + + "github.com/cespare/xxhash/v2" + "github.com/gofrs/uuid/v5" + + "github.com/elastic/beats/v7/auditbeat/datastore" + "github.com/elastic/beats/v7/auditbeat/helper/hasher" + "github.com/elastic/beats/v7/libbeat/common/capabilities" + "github.com/elastic/beats/v7/metricbeat/mb" + "github.com/elastic/beats/v7/x-pack/auditbeat/cache" + "github.com/elastic/beats/v7/x-pack/auditbeat/module/system" + "github.com/elastic/elastic-agent-libs/mapstr" + "github.com/elastic/go-sysinfo" + "github.com/elastic/go-sysinfo/types" +) + +const ( + bucketName = "auditbeat.process.v1" + bucketKeyStateTimestamp = "state_timestamp" +) + +// SysinfoMetricSet collects data about the host. +type SysInfoMetricSet struct { + system.SystemMetricSet + MetricSet + hasher *hasher.FileHasher + cache *cache.Cache + bucket datastore.Bucket + lastState time.Time + + suppressPermissionWarnings bool +} + +// Process represents information about a process. +type Process struct { + Info types.ProcessInfo + UserInfo *types.UserInfo + User *user.User + Group *user.Group + CapEffective []string + CapPermitted []string + Hashes map[hasher.HashType]hasher.Digest + Error error +} + +// Hash creates a hash for Process. +func (p Process) Hash() uint64 { + h := xxhash.New() + //nolint:errcheck // always return nil err + h.WriteString(strconv.Itoa(p.Info.PID)) + //nolint:errcheck // always return nil err + h.WriteString(p.Info.StartTime.String()) + return h.Sum64() +} + +func (p Process) toMapStr() mapstr.M { + return mapstr.M{ + // https://github.com/elastic/ecs#-process-fields + "name": p.Info.Name, + "args": p.Info.Args, + "pid": p.Info.PID, + "parent": mapstr.M{ + "pid": p.Info.PPID, + }, + "working_directory": p.Info.CWD, + "executable": p.Info.Exe, + "start": p.Info.StartTime, + } +} + +// NewFromSysInfo constructs a new MetricSet backed by go-sysinfo. +func NewFromSysInfo(base mb.BaseMetricSet, ms MetricSet) (mb.MetricSet, error) { + bucket, err := datastore.OpenBucket(bucketName) + if err != nil { + return nil, fmt.Errorf("failed to open persistent datastore: %w", err) + } + + // Load from disk: Time when state was last sent + var lastState time.Time + err = bucket.Load(bucketKeyStateTimestamp, func(blob []byte) error { + if len(blob) > 0 { + return lastState.UnmarshalBinary(blob) + } + return nil + }) + if err != nil { + bucket.Close() + return nil, err + } + if !lastState.IsZero() { + ms.log.Debugf("Last state was sent at %v. Next state update by %v.", + lastState, lastState.Add(ms.config.effectiveStatePeriod())) + } else { + ms.log.Debug("No state timestamp found") + } + + hasher, err := hasher.NewFileHasher(ms.config.HasherConfig, nil) + if err != nil { + bucket.Close() + return nil, err + } + + if runtime.GOOS != "windows" && os.Geteuid() != 0 { + ms.log.Warn("Running as non-root user, will likely not report all processes.") + } + + sm := &SysInfoMetricSet{ + SystemMetricSet: system.NewSystemMetricSet(base), + MetricSet: ms, + cache: cache.New(), + bucket: bucket, + lastState: lastState, + hasher: hasher, + } + + return sm, nil +} + +// Close cleans up the MetricSet when it finishes. +func (ms *SysInfoMetricSet) Close() error { + if ms.bucket != nil { + return ms.bucket.Close() + } + return nil +} + +// Fetch collects process information. It is invoked periodically. +func (ms *SysInfoMetricSet) Fetch(report mb.ReporterV2) { + needsStateUpdate := time.Since(ms.lastState) > ms.config.effectiveStatePeriod() + if needsStateUpdate || ms.cache.IsEmpty() { + ms.log.Debugf("State update needed (needsStateUpdate=%v, cache.IsEmpty()=%v)", needsStateUpdate, ms.cache.IsEmpty()) + err := ms.reportState(report) + if err != nil { + ms.log.Error(err) + report.Error(err) + } + ms.log.Debugf("Next state update by %v", ms.lastState.Add(ms.config.effectiveStatePeriod())) + } + + err := ms.reportChanges(report) + if err != nil { + ms.log.Error(err) + report.Error(err) + } +} + +// reportState reports all running processes on the system. +func (ms *SysInfoMetricSet) reportState(report mb.ReporterV2) error { + // Only update lastState if this state update was regularly scheduled, + // i.e. not caused by an Auditbeat restart (when the cache would be empty). + if !ms.cache.IsEmpty() { + ms.lastState = time.Now() + } + + processes, err := ms.getProcesses() + if err != nil { + return fmt.Errorf("failed to get process infos: %w", err) + } + ms.log.Debugf("Found %v processes", len(processes)) + + stateID, err := uuid.NewV4() + if err != nil { + return fmt.Errorf("error generating state ID: %w", err) + } + for _, p := range processes { + ms.enrichProcess(p) + + if p.Error == nil { + event := ms.processEvent(p, eventTypeState, eventActionExistingProcess) + event.RootFields.Put("event.id", stateID.String()) + report.Event(event) + } else { + ms.log.Warn(p.Error) + report.Event(ms.processEvent(p, eventTypeEvent, eventActionProcessError)) + } + } + + if ms.cache != nil { + // This will initialize the cache with the current processes + ms.cache.DiffAndUpdateCache(convertToCacheable(processes)) + } + + // Save time so we know when to send the state again (config.StatePeriod) + timeBytes, err := ms.lastState.MarshalBinary() + if err != nil { + return err + } + err = ms.bucket.Store(bucketKeyStateTimestamp, timeBytes) + if err != nil { + return fmt.Errorf("error writing state timestamp to disk: %w", err) + } + + return nil +} + +// reportChanges detects and reports any changes to processes on this system since the last call. +func (ms *SysInfoMetricSet) reportChanges(report mb.ReporterV2) error { + processes, err := ms.getProcesses() + if err != nil { + return fmt.Errorf("failed to get processes: %w", err) + } + ms.log.Debugf("Found %v processes", len(processes)) + + started, stopped := ms.cache.DiffAndUpdateCache(convertToCacheable(processes)) + + for _, cacheValue := range started { + p, ok := cacheValue.(*Process) + if !ok { + return fmt.Errorf("cache type error") + } + ms.enrichProcess(p) + + if p.Error == nil { + report.Event(ms.processEvent(p, eventTypeEvent, eventActionProcessStarted)) + } else { + ms.log.Warn(p.Error) + report.Event(ms.processEvent(p, eventTypeEvent, eventActionProcessError)) + } + } + + for _, cacheValue := range stopped { + p, ok := cacheValue.(*Process) + if !ok { + return fmt.Errorf("cache type error") + } + + if p.Error == nil { + report.Event(ms.processEvent(p, eventTypeEvent, eventActionProcessStopped)) + } + } + + return nil +} + +// enrichProcess enriches a process with user lookup information +// and executable file hash. +func (ms *SysInfoMetricSet) enrichProcess(process *Process) { + if process.UserInfo != nil { + goUser, err := user.LookupId(process.UserInfo.UID) + if err == nil { + process.User = goUser + } + + group, err := user.LookupGroupId(process.UserInfo.GID) + if err == nil { + process.Group = group + } + } + + if process.Info.Exe != "" { + sharedMntNS, err := isNsSharedWith(process.Info.PID, "mnt") + if err != nil { + if process.Error == nil { + process.Error = fmt.Errorf("failed to get namespaces for %v PID %v: %w", process.Info.Exe, process.Info.PID, err) + } + return + } + if !sharedMntNS { + return + } + hashes, err := ms.hasher.HashFile(process.Info.Exe) + if err != nil { + if process.Error == nil { + process.Error = fmt.Errorf("failed to hash executable %v for PID %v: %w", process.Info.Exe, process.Info.PID, err) + } + return + } + process.Hashes = hashes + } +} + +func (ms *SysInfoMetricSet) processEvent(process *Process, eventType string, action eventAction) mb.Event { + event := mb.Event{ + RootFields: mapstr.M{ + "event": mapstr.M{ + "kind": eventType, + "category": []string{"process"}, + "type": []string{action.Type()}, + "action": action.String(), + }, + "process": process.toMapStr(), + "message": processMessage(process, action), + }, + } + + if process.UserInfo != nil { + putIfNotEmpty(&event.RootFields, "user.id", process.UserInfo.UID) + putIfNotEmpty(&event.RootFields, "user.group.id", process.UserInfo.GID) + + putIfNotEmpty(&event.RootFields, "user.effective.id", process.UserInfo.EUID) + putIfNotEmpty(&event.RootFields, "user.effective.group.id", process.UserInfo.EGID) + + putIfNotEmpty(&event.RootFields, "user.saved.id", process.UserInfo.SUID) + putIfNotEmpty(&event.RootFields, "user.saved.group.id", process.UserInfo.SGID) + } + + if process.User != nil { + if process.User.Username != "" { + event.RootFields.Put("user.name", process.User.Username) + } else if process.User.Name != "" { + event.RootFields.Put("user.name", process.User.Name) + } + } + + if process.Group != nil { + event.RootFields.Put("user.group.name", process.Group.Name) + } + + if len(process.CapEffective) > 0 { + event.RootFields.Put("process.thread.capabilities.effective", process.CapEffective) + } + if len(process.CapPermitted) > 0 { + event.RootFields.Put("process.thread.capabilities.permitted", process.CapPermitted) + } + + if process.Hashes != nil { + for hashType, digest := range process.Hashes { + fieldName := "process.hash." + string(hashType) + event.RootFields.Put(fieldName, digest) + } + } + + if process.Error != nil { + event.RootFields.Put("error.message", process.Error.Error()) + } + + if ms.HostID() != "" { + event.RootFields.Put("process.entity_id", + entityID(ms.HostID(), process.Info.PID, process.Info.StartTime)) + } + + return event +} + +func putIfNotEmpty(mapstr *mapstr.M, key string, value string) { + if value != "" { + mapstr.Put(key, value) + } +} + +func processMessage(process *Process, action eventAction) string { + if process.Error != nil { + return fmt.Sprintf("ERROR for PID %d: %v", process.Info.PID, process.Error) + } + + var actionString string + switch action { + case eventActionProcessStarted: + actionString = "STARTED" + case eventActionProcessStopped: + actionString = "STOPPED" + case eventActionExistingProcess: + actionString = "is RUNNING" + } + + var userString string + if process.User != nil { + userString = fmt.Sprintf(" by user %v", process.User.Username) + } + + return fmt.Sprintf("Process %v (PID: %d)%v %v", + process.Info.Name, process.Info.PID, userString, actionString) +} + +func convertToCacheable(processes []*Process) []cache.Cacheable { + c := make([]cache.Cacheable, 0, len(processes)) + + for _, p := range processes { + c = append(c, p) + } + + return c +} + +func (ms *SysInfoMetricSet) getProcesses() ([]*Process, error) { + sysinfoProcs, err := sysinfo.Processes() + if err != nil { + return nil, fmt.Errorf("failed to fetch processes: %w", err) + } + + processes := make([]*Process, 0, len(sysinfoProcs)) + for _, sysinfoProc := range sysinfoProcs { + var process *Process + + pInfo, err := sysinfoProc.Info() + if err != nil { + if os.IsNotExist(err) { + // Skip - process probably just terminated since our call to Processes(). + continue + } + + if os.Geteuid() != 0 && os.IsPermission(err) { + // Running as non-root, permission issues when trying to access + // other user's private process information are expected. + + if !ms.suppressPermissionWarnings { + ms.log.Warnf("Failed to load process information for PID %d as non-root user. "+ + "Will suppress further errors of this kind. Error: %v", sysinfoProc.PID(), err) + + // Only warn once at the start of Auditbeat. + ms.suppressPermissionWarnings = true + } + + continue + } + + // Record what we can and continue + process = &Process{ + Info: pInfo, + Error: fmt.Errorf("failed to load process information for PID %d: %w", sysinfoProc.PID(), err), + } + process.Info.PID = sysinfoProc.PID() // in case pInfo did not contain it + } else { + process = &Process{ + Info: pInfo, + } + } + + userInfo, err := sysinfoProc.User() + if err != nil { + if process.Error == nil { + process.Error = fmt.Errorf("failed to load user for PID %d: %w", sysinfoProc.PID(), err) + } + } else { + process.UserInfo = &userInfo + } + + // Exclude Linux kernel processes, they are not very interesting. + if runtime.GOOS == "linux" { + if userInfo.UID == "0" && process.Info.Exe == "" { + continue + } + + // Fetch Effective and Permitted capabilities + process.CapEffective, err = capabilities.FromPid(capabilities.Effective, pInfo.PID) + if err != nil && process.Error == nil { + process.Error = err + } + process.CapPermitted, err = capabilities.FromPid(capabilities.Permitted, pInfo.PID) + if err != nil && process.Error == nil { + process.Error = err + } + } + + processes = append(processes, process) + } + + return processes, nil +} diff --git a/x-pack/auditbeat/module/system/process/process.go b/x-pack/auditbeat/module/system/process/process.go index 793bb70a4fb0..c79e87ce0fad 100644 --- a/x-pack/auditbeat/module/system/process/process.go +++ b/x-pack/auditbeat/module/system/process/process.go @@ -7,40 +7,29 @@ package process import ( "encoding/binary" "fmt" - "os" - "os/user" - "runtime" - "strconv" "time" - "github.com/cespare/xxhash/v2" - "github.com/gofrs/uuid/v5" - "github.com/elastic/beats/v7/auditbeat/ab" - "github.com/elastic/beats/v7/auditbeat/datastore" - "github.com/elastic/beats/v7/auditbeat/helper/hasher" - "github.com/elastic/beats/v7/libbeat/common/capabilities" "github.com/elastic/beats/v7/libbeat/common/cfgwarn" "github.com/elastic/beats/v7/metricbeat/mb" - "github.com/elastic/beats/v7/x-pack/auditbeat/cache" "github.com/elastic/beats/v7/x-pack/auditbeat/module/system" "github.com/elastic/elastic-agent-libs/logp" - "github.com/elastic/elastic-agent-libs/mapstr" - "github.com/elastic/go-sysinfo" - "github.com/elastic/go-sysinfo/types" ) const ( metricsetName = "process" namespace = "system.audit.process" - bucketName = "auditbeat.process.v1" - bucketKeyStateTimestamp = "state_timestamp" - eventTypeState = "state" eventTypeEvent = "event" ) +// MetricSet collects data about the host. +type MetricSet struct { + config Config + log *logp.Logger +} + type eventAction uint8 const ( @@ -87,439 +76,29 @@ func init() { ) } -// MetricSet collects data about the host. -type MetricSet struct { - system.SystemMetricSet - config Config - cache *cache.Cache - log *logp.Logger - bucket datastore.Bucket - lastState time.Time - hasher *hasher.FileHasher - - suppressPermissionWarnings bool -} +// New constructs a new MetricSet. +func New(base mb.BaseMetricSet) (mb.MetricSet, error) { + var ms MetricSet -// Process represents information about a process. -type Process struct { - Info types.ProcessInfo - UserInfo *types.UserInfo - User *user.User - Group *user.Group - CapEffective []string - CapPermitted []string - Hashes map[hasher.HashType]hasher.Digest - Error error -} + cfgwarn.Beta("The %v/%v dataset is beta", system.ModuleName, metricsetName) -// Hash creates a hash for Process. -func (p Process) Hash() uint64 { - h := xxhash.New() - //nolint:errcheck // always return nil err - h.WriteString(strconv.Itoa(p.Info.PID)) - //nolint:errcheck // always return nil err - h.WriteString(p.Info.StartTime.String()) - return h.Sum64() -} + ms.config = defaultConfig + ms.log = logp.NewLogger(metricsetName) -func (p Process) toMapStr() mapstr.M { - return mapstr.M{ - // https://github.com/elastic/ecs#-process-fields - "name": p.Info.Name, - "args": p.Info.Args, - "pid": p.Info.PID, - "parent": mapstr.M{ - "pid": p.Info.PPID, - }, - "working_directory": p.Info.CWD, - "executable": p.Info.Exe, - "start": p.Info.StartTime, + if err := base.Module().UnpackConfig(&ms.config); err != nil { + return nil, fmt.Errorf("failed to unpack the %v/%v config: %w", system.ModuleName, metricsetName, err) } + + return NewFromSysInfo(base, ms) } // entityID creates an ID that uniquely identifies this process across machines. -func (p Process) entityID(hostID string) string { +func entityID(hostID string, pid int, startTime time.Time) string { h := system.NewEntityHash() h.Write([]byte(hostID)) //nolint:errcheck // no error handling - binary.Write(h, binary.LittleEndian, int64(p.Info.PID)) + binary.Write(h, binary.LittleEndian, int64(pid)) //nolint:errcheck // no error handling - binary.Write(h, binary.LittleEndian, int64(p.Info.StartTime.Nanosecond())) + binary.Write(h, binary.LittleEndian, int64(startTime.Nanosecond())) return h.Sum() } - -// New constructs a new MetricSet. -func New(base mb.BaseMetricSet) (mb.MetricSet, error) { - cfgwarn.Beta("The %v/%v dataset is beta", system.ModuleName, metricsetName) - - config := defaultConfig - if err := base.Module().UnpackConfig(&config); err != nil { - return nil, fmt.Errorf("failed to unpack the %v/%v config: %w", system.ModuleName, metricsetName, err) - } - - bucket, err := datastore.OpenBucket(bucketName) - if err != nil { - return nil, fmt.Errorf("failed to open persistent datastore: %w", err) - } - - hasher, err := hasher.NewFileHasher(config.HasherConfig, nil) - if err != nil { - return nil, err - } - - ms := &MetricSet{ - SystemMetricSet: system.NewSystemMetricSet(base), - config: config, - log: logp.NewLogger(metricsetName), - cache: cache.New(), - bucket: bucket, - hasher: hasher, - } - - // Load from disk: Time when state was last sent - err = bucket.Load(bucketKeyStateTimestamp, func(blob []byte) error { - if len(blob) > 0 { - return ms.lastState.UnmarshalBinary(blob) - } - return nil - }) - if err != nil { - return nil, err - } - if !ms.lastState.IsZero() { - ms.log.Debugf("Last state was sent at %v. Next state update by %v.", ms.lastState, ms.lastState.Add(ms.config.effectiveStatePeriod())) - } else { - ms.log.Debug("No state timestamp found") - } - - if runtime.GOOS != "windows" && os.Geteuid() != 0 { - ms.log.Warn("Running as non-root user, will likely not report all processes.") - } - - return ms, nil -} - -// Close cleans up the MetricSet when it finishes. -func (ms *MetricSet) Close() error { - if ms.bucket != nil { - return ms.bucket.Close() - } - return nil -} - -// Fetch collects process information. It is invoked periodically. -func (ms *MetricSet) Fetch(report mb.ReporterV2) { - needsStateUpdate := time.Since(ms.lastState) > ms.config.effectiveStatePeriod() - if needsStateUpdate || ms.cache.IsEmpty() { - ms.log.Debugf("State update needed (needsStateUpdate=%v, cache.IsEmpty()=%v)", needsStateUpdate, ms.cache.IsEmpty()) - err := ms.reportState(report) - if err != nil { - ms.log.Error(err) - report.Error(err) - } - ms.log.Debugf("Next state update by %v", ms.lastState.Add(ms.config.effectiveStatePeriod())) - } - - err := ms.reportChanges(report) - if err != nil { - ms.log.Error(err) - report.Error(err) - } -} - -// reportState reports all running processes on the system. -func (ms *MetricSet) reportState(report mb.ReporterV2) error { - // Only update lastState if this state update was regularly scheduled, - // i.e. not caused by an Auditbeat restart (when the cache would be empty). - if !ms.cache.IsEmpty() { - ms.lastState = time.Now() - } - - processes, err := ms.getProcesses() - if err != nil { - return fmt.Errorf("failed to get process infos: %w", err) - } - ms.log.Debugf("Found %v processes", len(processes)) - - stateID, err := uuid.NewV4() - if err != nil { - return fmt.Errorf("error generating state ID: %w", err) - } - for _, p := range processes { - ms.enrichProcess(p) - - if p.Error == nil { - event := ms.processEvent(p, eventTypeState, eventActionExistingProcess) - event.RootFields.Put("event.id", stateID.String()) - report.Event(event) - } else { - ms.log.Warn(p.Error) - report.Event(ms.processEvent(p, eventTypeEvent, eventActionProcessError)) - } - } - - if ms.cache != nil { - // This will initialize the cache with the current processes - ms.cache.DiffAndUpdateCache(convertToCacheable(processes)) - } - - // Save time so we know when to send the state again (config.StatePeriod) - timeBytes, err := ms.lastState.MarshalBinary() - if err != nil { - return err - } - err = ms.bucket.Store(bucketKeyStateTimestamp, timeBytes) - if err != nil { - return fmt.Errorf("error writing state timestamp to disk: %w", err) - } - - return nil -} - -// reportChanges detects and reports any changes to processes on this system since the last call. -func (ms *MetricSet) reportChanges(report mb.ReporterV2) error { - processes, err := ms.getProcesses() - if err != nil { - return fmt.Errorf("failed to get processes: %w", err) - } - ms.log.Debugf("Found %v processes", len(processes)) - - started, stopped := ms.cache.DiffAndUpdateCache(convertToCacheable(processes)) - - for _, cacheValue := range started { - p := cacheValue.(*Process) - ms.enrichProcess(p) - - if p.Error == nil { - report.Event(ms.processEvent(p, eventTypeEvent, eventActionProcessStarted)) - } else { - ms.log.Warn(p.Error) - report.Event(ms.processEvent(p, eventTypeEvent, eventActionProcessError)) - } - } - - for _, cacheValue := range stopped { - p := cacheValue.(*Process) - - if p.Error == nil { - report.Event(ms.processEvent(p, eventTypeEvent, eventActionProcessStopped)) - } - } - - return nil -} - -// enrichProcess enriches a process with user lookup information -// and executable file hash. -func (ms *MetricSet) enrichProcess(process *Process) { - if process.UserInfo != nil { - goUser, err := user.LookupId(process.UserInfo.UID) - if err == nil { - process.User = goUser - } - - group, err := user.LookupGroupId(process.UserInfo.GID) - if err == nil { - process.Group = group - } - } - - if process.Info.Exe != "" { - sharedMntNS, err := isNsSharedWith(process.Info.PID, "mnt") - if err != nil { - if process.Error == nil { - process.Error = fmt.Errorf("failed to get namespaces for %v PID %v: %w", process.Info.Exe, process.Info.PID, err) - } - return - } - if !sharedMntNS { - return - } - hashes, err := ms.hasher.HashFile(process.Info.Exe) - if err != nil { - if process.Error == nil { - process.Error = fmt.Errorf("failed to hash executable %v for PID %v: %w", process.Info.Exe, process.Info.PID, err) - } - return - } - process.Hashes = hashes - } -} - -func (ms *MetricSet) processEvent(process *Process, eventType string, action eventAction) mb.Event { - event := mb.Event{ - RootFields: mapstr.M{ - "event": mapstr.M{ - "kind": eventType, - "category": []string{"process"}, - "type": []string{action.Type()}, - "action": action.String(), - }, - "process": process.toMapStr(), - "message": processMessage(process, action), - }, - } - - if process.UserInfo != nil { - putIfNotEmpty(&event.RootFields, "user.id", process.UserInfo.UID) - putIfNotEmpty(&event.RootFields, "user.group.id", process.UserInfo.GID) - - putIfNotEmpty(&event.RootFields, "user.effective.id", process.UserInfo.EUID) - putIfNotEmpty(&event.RootFields, "user.effective.group.id", process.UserInfo.EGID) - - putIfNotEmpty(&event.RootFields, "user.saved.id", process.UserInfo.SUID) - putIfNotEmpty(&event.RootFields, "user.saved.group.id", process.UserInfo.SGID) - } - - if process.User != nil { - if process.User.Username != "" { - event.RootFields.Put("user.name", process.User.Username) - } else if process.User.Name != "" { - event.RootFields.Put("user.name", process.User.Name) - } - } - - if process.Group != nil { - event.RootFields.Put("user.group.name", process.Group.Name) - } - - if len(process.CapEffective) > 0 { - event.RootFields.Put("process.thread.capabilities.effective", process.CapEffective) - } - if len(process.CapPermitted) > 0 { - event.RootFields.Put("process.thread.capabilities.permitted", process.CapPermitted) - } - - if process.Hashes != nil { - for hashType, digest := range process.Hashes { - fieldName := "process.hash." + string(hashType) - event.RootFields.Put(fieldName, digest) - } - } - - if process.Error != nil { - event.RootFields.Put("error.message", process.Error.Error()) - } - - if ms.HostID() != "" { - event.RootFields.Put("process.entity_id", process.entityID(ms.HostID())) - } - - return event -} - -func putIfNotEmpty(mapstr *mapstr.M, key string, value string) { - if value != "" { - mapstr.Put(key, value) - } -} - -func processMessage(process *Process, action eventAction) string { - if process.Error != nil { - return fmt.Sprintf("ERROR for PID %d: %v", process.Info.PID, process.Error) - } - - var actionString string - switch action { - case eventActionProcessStarted: - actionString = "STARTED" - case eventActionProcessStopped: - actionString = "STOPPED" - case eventActionExistingProcess: - actionString = "is RUNNING" - } - - var userString string - if process.User != nil { - userString = fmt.Sprintf(" by user %v", process.User.Username) - } - - return fmt.Sprintf("Process %v (PID: %d)%v %v", - process.Info.Name, process.Info.PID, userString, actionString) -} - -func convertToCacheable(processes []*Process) []cache.Cacheable { - c := make([]cache.Cacheable, 0, len(processes)) - - for _, p := range processes { - c = append(c, p) - } - - return c -} - -func (ms *MetricSet) getProcesses() ([]*Process, error) { - sysinfoProcs, err := sysinfo.Processes() - if err != nil { - return nil, fmt.Errorf("failed to fetch processes: %w", err) - } - - processes := make([]*Process, 0, len(sysinfoProcs)) - for _, sysinfoProc := range sysinfoProcs { - var process *Process - - pInfo, err := sysinfoProc.Info() - if err != nil { - if os.IsNotExist(err) { - // Skip - process probably just terminated since our call to Processes(). - continue - } - - if os.Geteuid() != 0 && os.IsPermission(err) { - // Running as non-root, permission issues when trying to access - // other user's private process information are expected. - - if !ms.suppressPermissionWarnings { - ms.log.Warnf("Failed to load process information for PID %d as non-root user. "+ - "Will suppress further errors of this kind. Error: %v", sysinfoProc.PID(), err) - - // Only warn once at the start of Auditbeat. - ms.suppressPermissionWarnings = true - } - - continue - } - - // Record what we can and continue - process = &Process{ - Info: pInfo, - Error: fmt.Errorf("failed to load process information for PID %d: %w", sysinfoProc.PID(), err), - } - process.Info.PID = sysinfoProc.PID() // in case pInfo did not contain it - } else { - process = &Process{ - Info: pInfo, - } - } - - userInfo, err := sysinfoProc.User() - if err != nil { - if process.Error == nil { - process.Error = fmt.Errorf("failed to load user for PID %d: %w", sysinfoProc.PID(), err) - } - } else { - process.UserInfo = &userInfo - } - - // Exclude Linux kernel processes, they are not very interesting. - if runtime.GOOS == "linux" { - if userInfo.UID == "0" && process.Info.Exe == "" { - continue - } - - // Fetch Effective and Permitted capabilities - process.CapEffective, err = capabilities.FromPid(capabilities.Effective, pInfo.PID) - if err != nil && process.Error == nil { - process.Error = err - } - process.CapPermitted, err = capabilities.FromPid(capabilities.Permitted, pInfo.PID) - if err != nil && process.Error == nil { - process.Error = err - } - } - - processes = append(processes, process) - } - - return processes, nil -} diff --git a/x-pack/auditbeat/module/system/process/process_test.go b/x-pack/auditbeat/module/system/process/process_test.go index 25508072f021..17283fe9e346 100644 --- a/x-pack/auditbeat/module/system/process/process_test.go +++ b/x-pack/auditbeat/module/system/process/process_test.go @@ -27,9 +27,9 @@ func TestData(t *testing.T) { f := mbtest.NewReportingMetricSetV2WithRegistry(t, getConfig(), ab.Registry) // Set lastState and add test process to cache so it will be reported as stopped. - f.(*MetricSet).lastState = time.Now() + f.(*SysInfoMetricSet).lastState = time.Now() p := testProcess() - f.(*MetricSet).cache.DiffAndUpdateCache(convertToCacheable([]*Process{p})) + f.(*SysInfoMetricSet).cache.DiffAndUpdateCache(convertToCacheable([]*Process{p})) events, errs := mbtest.ReportingFetchV2(f) if len(errs) > 0 { @@ -56,7 +56,8 @@ func getConfig() map[string]interface{} { } func TestProcessEvent(t *testing.T) { - ms := mbtest.NewReportingMetricSetV2WithRegistry(t, getConfig(), ab.Registry).(*MetricSet) + ms, ok := mbtest.NewReportingMetricSetV2WithRegistry(t, getConfig(), ab.Registry).(*SysInfoMetricSet) + assert.True(t, ok) eventType := eventTypeEvent eventAction := eventActionProcessStarted From 91070bf2a8b3a22022f747831ecad7e8159bba95 Mon Sep 17 00:00:00 2001 From: Kavindu Dodanduwa Date: Tue, 3 Dec 2024 14:43:04 -0800 Subject: [PATCH 13/48] [AWS] improve S3 input states copy by only storing filtered entries (#41869) * s3 state imporvement with prefix filtering Signed-off-by: Kavindu Dodanduwa * add changelog entry Signed-off-by: Kavindu Dodanduwa --------- Signed-off-by: Kavindu Dodanduwa --- CHANGELOG.next.asciidoc | 1 + .../input/awss3/input_benchmark_test.go | 2 +- x-pack/filebeat/input/awss3/s3_input.go | 2 +- x-pack/filebeat/input/awss3/s3_test.go | 9 +- x-pack/filebeat/input/awss3/states.go | 28 ++++-- x-pack/filebeat/input/awss3/states_test.go | 89 +++++++++++++++++-- 6 files changed, 112 insertions(+), 19 deletions(-) diff --git a/CHANGELOG.next.asciidoc b/CHANGELOG.next.asciidoc index c9b8f120e540..5721762aa966 100644 --- a/CHANGELOG.next.asciidoc +++ b/CHANGELOG.next.asciidoc @@ -353,6 +353,7 @@ https://github.com/elastic/beats/compare/v8.8.1\...main[Check the HEAD diff] - Refactor & cleanup with updates to default values and documentation. {pull}41834[41834] - Update CEL mito extensions to v1.16.0. {pull}41727[41727] - Add evaluation state dump debugging option to CEL input. {pull}41335[41335] +- Improve S3 polling mode states registry when using list prefix option. {pull}41869[41869] *Auditbeat* diff --git a/x-pack/filebeat/input/awss3/input_benchmark_test.go b/x-pack/filebeat/input/awss3/input_benchmark_test.go index 54e227736025..319d8c3b9aa3 100644 --- a/x-pack/filebeat/input/awss3/input_benchmark_test.go +++ b/x-pack/filebeat/input/awss3/input_benchmark_test.go @@ -339,7 +339,7 @@ func benchmarkInputS3(t *testing.T, numberOfWorkers int) testing.BenchmarkResult s3API.pagerConstant = newS3PagerConstant(curConfig.BucketListPrefix) store := openTestStatestore() - states, err := newStates(nil, store) + states, err := newStates(nil, store, "") assert.NoError(t, err, "states creation should succeed") s3EventHandlerFactory := newS3ObjectProcessorFactory(metrics, s3API, config.FileSelectors, backupConfig{}) diff --git a/x-pack/filebeat/input/awss3/s3_input.go b/x-pack/filebeat/input/awss3/s3_input.go index 6775a1be0336..bc8a21495e54 100644 --- a/x-pack/filebeat/input/awss3/s3_input.go +++ b/x-pack/filebeat/input/awss3/s3_input.go @@ -66,7 +66,7 @@ func (in *s3PollerInput) Run( var err error // Load the persistent S3 polling state. - in.states, err = newStates(in.log, in.store) + in.states, err = newStates(in.log, in.store, in.config.BucketListPrefix) if err != nil { return fmt.Errorf("can not start persistent store: %w", err) } diff --git a/x-pack/filebeat/input/awss3/s3_test.go b/x-pack/filebeat/input/awss3/s3_test.go index b0b19d828318..a1e9e02b4263 100644 --- a/x-pack/filebeat/input/awss3/s3_test.go +++ b/x-pack/filebeat/input/awss3/s3_test.go @@ -22,6 +22,7 @@ func TestS3Poller(t *testing.T) { logp.TestingSetup() const bucket = "bucket" + const listPrefix = "key" const numberOfWorkers = 5 const pollInterval = 2 * time.Second const testTimeout = 1 * time.Second @@ -127,7 +128,7 @@ func TestS3Poller(t *testing.T) { Return(nil, errFakeConnectivityFailure) s3ObjProc := newS3ObjectProcessorFactory(nil, mockAPI, nil, backupConfig{}) - states, err := newStates(nil, store) + states, err := newStates(nil, store, listPrefix) require.NoError(t, err, "states creation must succeed") poller := &s3PollerInput{ log: logp.NewLogger(inputName), @@ -135,7 +136,7 @@ func TestS3Poller(t *testing.T) { NumberOfWorkers: numberOfWorkers, BucketListInterval: pollInterval, BucketARN: bucket, - BucketListPrefix: "key", + BucketListPrefix: listPrefix, RegionName: "region", }, s3: mockAPI, @@ -265,7 +266,7 @@ func TestS3Poller(t *testing.T) { Return(nil, errFakeConnectivityFailure) s3ObjProc := newS3ObjectProcessorFactory(nil, mockS3, nil, backupConfig{}) - states, err := newStates(nil, store) + states, err := newStates(nil, store, listPrefix) require.NoError(t, err, "states creation must succeed") poller := &s3PollerInput{ log: logp.NewLogger(inputName), @@ -273,7 +274,7 @@ func TestS3Poller(t *testing.T) { NumberOfWorkers: numberOfWorkers, BucketListInterval: pollInterval, BucketARN: bucket, - BucketListPrefix: "key", + BucketListPrefix: listPrefix, RegionName: "region", }, s3: mockS3, diff --git a/x-pack/filebeat/input/awss3/states.go b/x-pack/filebeat/input/awss3/states.go index cb40abbd41f0..8aef3de1c99e 100644 --- a/x-pack/filebeat/input/awss3/states.go +++ b/x-pack/filebeat/input/awss3/states.go @@ -28,23 +28,27 @@ type states struct { // storeLock must be held to access store. store *statestore.Store storeLock sync.Mutex + + // Accepted prefixes of state keys of this registry + keyPrefix string } // newStates generates a new states registry. -func newStates(log *logp.Logger, stateStore beater.StateStore) (*states, error) { +func newStates(log *logp.Logger, stateStore beater.StateStore, listPrefix string) (*states, error) { store, err := stateStore.Access() if err != nil { return nil, fmt.Errorf("can't access persistent store: %w", err) } - stateTable, err := loadS3StatesFromRegistry(log, store) + stateTable, err := loadS3StatesFromRegistry(log, store, listPrefix) if err != nil { return nil, fmt.Errorf("loading S3 input state: %w", err) } return &states{ - store: store, - states: stateTable, + store: store, + states: stateTable, + keyPrefix: listPrefix, }, nil } @@ -57,6 +61,12 @@ func (s *states) IsProcessed(state state) bool { } func (s *states) AddState(state state) error { + if !strings.HasPrefix(state.Key, s.keyPrefix) { + // Note - This failure should not happen since we create a dedicated state instance per input. + // Yet, this is here to avoid any wiring errors within the component. + return fmt.Errorf("expected prefix %s in key %s, skipping state registering", s.keyPrefix, state.Key) + } + id := state.ID() // Update in-memory copy s.statesLock.Lock() @@ -79,7 +89,9 @@ func (s *states) Close() { s.storeLock.Unlock() } -func loadS3StatesFromRegistry(log *logp.Logger, store *statestore.Store) (map[string]state, error) { +// loadS3StatesFromRegistry loads a copy of the registry states. +// If prefix is set, entries will match the provided prefix(including empty prefix) +func loadS3StatesFromRegistry(log *logp.Logger, store *statestore.Store, prefix string) (map[string]state, error) { stateTable := map[string]state{} err := store.Each(func(key string, dec statestore.ValueDecoder) (bool, error) { if !strings.HasPrefix(key, awsS3ObjectStatePrefix) { @@ -103,7 +115,11 @@ func loadS3StatesFromRegistry(log *logp.Logger, store *statestore.Store) (map[st return true, nil } - stateTable[st.ID()] = st + // filter based on prefix and add entry to local copy + if strings.HasPrefix(st.Key, prefix) { + stateTable[st.ID()] = st + } + return true, nil }) if err != nil { diff --git a/x-pack/filebeat/input/awss3/states_test.go b/x-pack/filebeat/input/awss3/states_test.go index dc345d5f88e8..328b57003cd1 100644 --- a/x-pack/filebeat/input/awss3/states_test.go +++ b/x-pack/filebeat/input/awss3/states_test.go @@ -11,6 +11,7 @@ import ( "github.com/elastic/beats/v7/filebeat/beater" "github.com/elastic/beats/v7/libbeat/statestore" "github.com/elastic/beats/v7/libbeat/statestore/storetest" + "github.com/elastic/elastic-agent-libs/logp" "github.com/stretchr/testify/assert" "github.com/stretchr/testify/require" @@ -62,14 +63,14 @@ func TestStatesAddStateAndIsProcessed(t *testing.T) { }, "not existing state": { statesEdit: func(states *states) { - states.AddState(testState2) + _ = states.AddState(testState2) }, state: testState1, expectedIsProcessed: false, }, "existing state": { statesEdit: func(states *states) { - states.AddState(testState1) + _ = states.AddState(testState1) }, state: testState1, expectedIsProcessed: true, @@ -78,7 +79,7 @@ func TestStatesAddStateAndIsProcessed(t *testing.T) { statesEdit: func(states *states) { state := testState1 state.Stored = true - states.AddState(state) + _ = states.AddState(state) }, state: testState1, shouldReload: true, @@ -88,7 +89,7 @@ func TestStatesAddStateAndIsProcessed(t *testing.T) { statesEdit: func(states *states) { state := testState1 state.Failed = true - states.AddState(state) + _ = states.AddState(state) }, state: testState1, shouldReload: true, @@ -96,7 +97,7 @@ func TestStatesAddStateAndIsProcessed(t *testing.T) { }, "existing unprocessed state is not persisted": { statesEdit: func(states *states) { - states.AddState(testState1) + _ = states.AddState(testState1) }, state: testState1, shouldReload: true, @@ -108,13 +109,13 @@ func TestStatesAddStateAndIsProcessed(t *testing.T) { test := test t.Run(name, func(t *testing.T) { store := openTestStatestore() - states, err := newStates(nil, store) + states, err := newStates(nil, store, "") require.NoError(t, err, "states creation must succeed") if test.statesEdit != nil { test.statesEdit(states) } if test.shouldReload { - states, err = newStates(nil, store) + states, err = newStates(nil, store, "") require.NoError(t, err, "states creation must succeed") } @@ -123,3 +124,77 @@ func TestStatesAddStateAndIsProcessed(t *testing.T) { }) } } + +func TestStatesPrefixHandling(t *testing.T) { + logger := logp.NewLogger("state-prefix-testing") + + t.Run("if prefix was set, accept only states with prefix", func(t *testing.T) { + // given + registry := openTestStatestore() + + // when - registry with prefix + st, err := newStates(logger, registry, "staging-") + require.NoError(t, err) + + // then - fail for non prefixed + err = st.AddState(newState("bucket", "production-logA", "etag", time.Now())) + require.Error(t, err) + + // then - pass for correctly prefixed + err = st.AddState(newState("bucket", "staging-logA", "etag", time.Now())) + require.NoError(t, err) + }) + + t.Run("states store only load entries matching the given prefix", func(t *testing.T) { + // given + registry := openTestStatestore() + + sA := newState("bucket", "A", "etag", time.Unix(1733221244, 0)) + sA.Stored = true + sStagingA := newState("bucket", "staging-A", "etag", time.Unix(1733224844, 0)) + sStagingA.Stored = true + sProdB := newState("bucket", "production/B", "etag", time.Unix(1733228444, 0)) + sProdB.Stored = true + sSpace := newState("bucket", " B", "etag", time.Unix(1733230444, 0)) + sSpace.Stored = true + + // add various states first with no prefix + st, err := newStates(logger, registry, "") + require.NoError(t, err) + + _ = st.AddState(sA) + _ = st.AddState(sStagingA) + _ = st.AddState(sProdB) + _ = st.AddState(sSpace) + + // Reload states and validate + + // when - no prefix reload + stNoPrefix, err := newStates(logger, registry, "") + require.NoError(t, err) + + require.True(t, stNoPrefix.IsProcessed(sA)) + require.True(t, stNoPrefix.IsProcessed(sStagingA)) + require.True(t, stNoPrefix.IsProcessed(sProdB)) + require.True(t, stNoPrefix.IsProcessed(sSpace)) + + // when - with prefix `staging-` + st, err = newStates(logger, registry, "staging-") + require.NoError(t, err) + + require.False(t, st.IsProcessed(sA)) + require.True(t, st.IsProcessed(sStagingA)) + require.False(t, st.IsProcessed(sProdB)) + require.False(t, st.IsProcessed(sSpace)) + + // when - with prefix `production/` + st, err = newStates(logger, registry, "production/") + require.NoError(t, err) + + require.False(t, st.IsProcessed(sA)) + require.False(t, st.IsProcessed(sStagingA)) + require.True(t, st.IsProcessed(sProdB)) + require.False(t, st.IsProcessed(sSpace)) + }) + +} From 3f51793e33da83d62bb9260d9957df62eaf69fb7 Mon Sep 17 00:00:00 2001 From: ShourieG Date: Wed, 4 Dec 2024 13:01:01 +0530 Subject: [PATCH 14/48] [filebeat][gcs] - Added support for retry config (#41862) * Added support for retry config along with necessary documentation and tests --- CHANGELOG.next.asciidoc | 1 + .../filebeat/docs/inputs/input-gcs.asciidoc | 40 ++++++++++ x-pack/filebeat/input/gcs/config.go | 21 ++++++ x-pack/filebeat/input/gcs/input.go | 7 +- x-pack/filebeat/input/gcs/input_stateless.go | 8 +- x-pack/filebeat/input/gcs/input_test.go | 75 +++++++++++++++++++ x-pack/filebeat/input/gcs/mock/mock.go | 40 ++++++++++ x-pack/filebeat/input/gcs/types.go | 1 + 8 files changed, 190 insertions(+), 3 deletions(-) diff --git a/CHANGELOG.next.asciidoc b/CHANGELOG.next.asciidoc index 5721762aa966..4ad010d29e27 100644 --- a/CHANGELOG.next.asciidoc +++ b/CHANGELOG.next.asciidoc @@ -353,6 +353,7 @@ https://github.com/elastic/beats/compare/v8.8.1\...main[Check the HEAD diff] - Refactor & cleanup with updates to default values and documentation. {pull}41834[41834] - Update CEL mito extensions to v1.16.0. {pull}41727[41727] - Add evaluation state dump debugging option to CEL input. {pull}41335[41335] +- Added support for retry configuration in GCS input. {issue}11580[11580] {pull}41862[41862] - Improve S3 polling mode states registry when using list prefix option. {pull}41869[41869] *Auditbeat* diff --git a/x-pack/filebeat/docs/inputs/input-gcs.asciidoc b/x-pack/filebeat/docs/inputs/input-gcs.asciidoc index 2a762ddec18a..d85a7393440e 100644 --- a/x-pack/filebeat/docs/inputs/input-gcs.asciidoc +++ b/x-pack/filebeat/docs/inputs/input-gcs.asciidoc @@ -164,6 +164,7 @@ Now let's explore the configuration attributes a bit more elaborately. 11. <> 12. <> 13. <> + 14. <> [id="attrib-project-id"] @@ -397,6 +398,45 @@ filebeat.inputs: The GCS APIs don't provide a direct way to filter files based on the timestamp, so the input will download all the files and then filter them based on the timestamp. This can cause a bottleneck in processing if the number of files are very high. It is recommended to use this attribute only when the number of files are limited or ample resources are available. This option scales vertically and not horizontally. +[id="attrib-retry-gcs"] +[float] +==== `retry` + +This attribute can be used to configure a list of sub attributes that directly control how the input should behave when a download for a file/object fails or gets interrupted. + + - `max_attempts`: This attribute defines the maximum number of retry attempts(including the initial api call) that should be attempted for a retryable error. The default value for this is `3`. + - `initial_backoff_duration`: This attribute defines the initial backoff time. The default value for this is `1s`. + - `max_backoff_duration`: This attribute defines the maximum backoff time. The default value for this is `30s`. + - `backoff_multiplier`: This attribute defines the backoff multiplication factor. The default value for this is `2`. + +NOTE: The `initial_backoff_duration` and `max_backoff_duration` attributes must have time units. Valid time units are `ns`, `us` (or `µs`), `ms`, `s`, `m`, `h`. + +By configuring these attributes, the user is given the flexibility to control how the input should behave when a download fails or gets interrupted. This attribute can only be +specified at the root level of the configuration and not at the bucket level. It applies uniformly to all the buckets. + +An example configuration is given below :- + +[source, yml] +---- +filebeat.inputs: +- type: gcs + project_id: my_project_id + auth.credentials_file.path: {{file_path}}/{{creds_file_name}}.json + retry: + max_attempts: 3 + initial_backoff_duration: 2s + max_backoff_duration: 60s + backoff_multiplier: 2 + buckets: + - name: obs-bucket + max_workers: 3 + poll: true + poll_interval: 11m + bucket_timeout: 10m +---- + +When configuring the `retry` attribute, the user should consider the `bucket_timeout` value. The `retry` attribute should be configured in such a way that the retries are completed within the `bucket_timeout` window. If the `retry` attribute is configured in such a way that the retries are not completed successfully within the `bucket_timeout` window, the input will suffer a `context timeout` for that specific object/file which it was retrying. This can cause gaps in ingested data to pile up over time. + [id="bucket-overrides"] *The sample configs below will explain the bucket level overriding of attributes a bit further :-* diff --git a/x-pack/filebeat/input/gcs/config.go b/x-pack/filebeat/input/gcs/config.go index 64f64c69bc5f..9a9f6dceadd4 100644 --- a/x-pack/filebeat/input/gcs/config.go +++ b/x-pack/filebeat/input/gcs/config.go @@ -50,6 +50,8 @@ type config struct { ExpandEventListFromField string `config:"expand_event_list_from_field"` // This field is only used for system test purposes, to override the HTTP endpoint. AlternativeHost string `config:"alternative_host"` + // Retry - Defines the retry configuration for the input. + Retry retryConfig `config:"retry"` } // bucket contains the config for each specific object storage bucket in the root account @@ -92,6 +94,19 @@ type jsonCredentialsConfig struct { AccountKey string `config:"account_key"` } +type retryConfig struct { + // MaxAttempts configures the maximum number of times an API call can be made in the case of retryable errors. + // For example, if you set MaxAttempts(5), the operation will be attempted up to 5 times total (initial call plus 4 retries). + // If you set MaxAttempts(1), the operation will be attempted only once and there will be no retries. This setting defaults to 3. + MaxAttempts int `config:"max_attempts" validate:"min=1"` + // InitialBackOffDuration is the initial value of the retry period, defaults to 1 second. + InitialBackOffDuration time.Duration `config:"initial_backoff_duration" validate:"min=1"` + // MaxBackOffDuration is the maximum value of the retry period, defaults to 30 seconds. + MaxBackOffDuration time.Duration `config:"max_backoff_duration" validate:"min=2"` + // BackOffMultiplier is the factor by which the retry period increases. It should be greater than 1 and defaults to 2. + BackOffMultiplier float64 `config:"backoff_multiplier" validate:"min=1.1"` +} + func (c authConfig) Validate() error { // credentials_file if c.CredentialsFile != nil { @@ -126,5 +141,11 @@ func defaultConfig() config { PollInterval: 5 * time.Minute, BucketTimeOut: 120 * time.Second, ParseJSON: false, + Retry: retryConfig{ + MaxAttempts: 3, + InitialBackOffDuration: time.Second, + MaxBackOffDuration: 30 * time.Second, + BackOffMultiplier: 2, + }, } } diff --git a/x-pack/filebeat/input/gcs/input.go b/x-pack/filebeat/input/gcs/input.go index 33e46d034d76..1d6bff8b857a 100644 --- a/x-pack/filebeat/input/gcs/input.go +++ b/x-pack/filebeat/input/gcs/input.go @@ -72,6 +72,7 @@ func configure(cfg *conf.C) ([]cursor.Source, cursor.Input, error) { ExpandEventListFromField: bucket.ExpandEventListFromField, FileSelectors: bucket.FileSelectors, ReaderConfig: bucket.ReaderConfig, + Retry: config.Retry, }) } @@ -158,9 +159,13 @@ func (input *gcsInput) Run(inputCtx v2.Context, src cursor.Source, } bucket := client.Bucket(currentSource.BucketName).Retryer( + // Use WithMaxAttempts to change the maximum number of attempts. + storage.WithMaxAttempts(currentSource.Retry.MaxAttempts), // Use WithBackoff to change the timing of the exponential backoff. storage.WithBackoff(gax.Backoff{ - Initial: 2 * time.Second, + Initial: currentSource.Retry.InitialBackOffDuration, + Max: currentSource.Retry.MaxBackOffDuration, + Multiplier: currentSource.Retry.BackOffMultiplier, }), // RetryAlways will retry the operation even if it is non-idempotent. // Since we are only reading, the operation is always idempotent diff --git a/x-pack/filebeat/input/gcs/input_stateless.go b/x-pack/filebeat/input/gcs/input_stateless.go index c0038bf31dce..b6901f0df25f 100644 --- a/x-pack/filebeat/input/gcs/input_stateless.go +++ b/x-pack/filebeat/input/gcs/input_stateless.go @@ -6,7 +6,6 @@ package gcs import ( "context" - "time" "cloud.google.com/go/storage" gax "github.com/googleapis/gax-go/v2" @@ -64,6 +63,7 @@ func (in *statelessInput) Run(inputCtx v2.Context, publisher stateless.Publisher ExpandEventListFromField: bucket.ExpandEventListFromField, FileSelectors: bucket.FileSelectors, ReaderConfig: bucket.ReaderConfig, + Retry: in.config.Retry, } st := newState() @@ -80,9 +80,13 @@ func (in *statelessInput) Run(inputCtx v2.Context, publisher stateless.Publisher }() bkt := client.Bucket(currentSource.BucketName).Retryer( + // Use WithMaxAttempts to change the maximum number of attempts. + storage.WithMaxAttempts(currentSource.Retry.MaxAttempts), // Use WithBackoff to change the timing of the exponential backoff. storage.WithBackoff(gax.Backoff{ - Initial: 2 * time.Second, + Initial: currentSource.Retry.InitialBackOffDuration, + Max: currentSource.Retry.MaxBackOffDuration, + Multiplier: currentSource.Retry.BackOffMultiplier, }), // RetryAlways will retry the operation even if it is non-idempotent. // Since we are only reading, the operation is always idempotent diff --git a/x-pack/filebeat/input/gcs/input_test.go b/x-pack/filebeat/input/gcs/input_test.go index 5595622c93e5..345c7c579096 100644 --- a/x-pack/filebeat/input/gcs/input_test.go +++ b/x-pack/filebeat/input/gcs/input_test.go @@ -520,6 +520,81 @@ func Test_StorageClient(t *testing.T) { mock.Gcs_test_new_object_docs_ata_json: true, }, }, + { + name: "RetryWithDefaultValues", + baseConfig: map[string]interface{}{ + "project_id": "elastic-sa", + "auth.credentials_file.path": "testdata/gcs_creds.json", + "max_workers": 1, + "poll": true, + "poll_interval": "1m", + "bucket_timeout": "1m", + "buckets": []map[string]interface{}{ + { + "name": "gcs-test-new", + }, + }, + }, + mockHandler: mock.GCSRetryServer, + expected: map[string]bool{ + mock.Gcs_test_new_object_ata_json: true, + mock.Gcs_test_new_object_data3_json: true, + mock.Gcs_test_new_object_docs_ata_json: true, + }, + }, + { + name: "RetryWithCustomValues", + baseConfig: map[string]interface{}{ + "project_id": "elastic-sa", + "auth.credentials_file.path": "testdata/gcs_creds.json", + "max_workers": 1, + "poll": true, + "poll_interval": "10s", + "bucket_timeout": "10s", + "retry": map[string]interface{}{ + "max_attempts": 5, + "initial_backoff_duration": "1s", + "max_backoff_duration": "3s", + "backoff_multiplier": 1.4, + }, + "buckets": []map[string]interface{}{ + { + "name": "gcs-test-new", + }, + }, + }, + mockHandler: mock.GCSRetryServer, + expected: map[string]bool{ + mock.Gcs_test_new_object_ata_json: true, + mock.Gcs_test_new_object_data3_json: true, + mock.Gcs_test_new_object_docs_ata_json: true, + }, + }, + { + name: "RetryMinimumValueCheck", + baseConfig: map[string]interface{}{ + "project_id": "elastic-sa", + "auth.credentials_file.path": "testdata/gcs_creds.json", + "max_workers": 1, + "poll": true, + "poll_interval": "10s", + "bucket_timeout": "10s", + "retry": map[string]interface{}{ + "max_attempts": 5, + "initial_backoff_duration": "1s", + "max_backoff_duration": "3s", + "backoff_multiplier": 1, + }, + "buckets": []map[string]interface{}{ + { + "name": "gcs-test-new", + }, + }, + }, + mockHandler: mock.GCSRetryServer, + expected: map[string]bool{}, + isError: errors.New("requires value >= 1.1 accessing 'retry.backoff_multiplier'"), + }, } for _, tt := range tests { t.Run(tt.name, func(t *testing.T) { diff --git a/x-pack/filebeat/input/gcs/mock/mock.go b/x-pack/filebeat/input/gcs/mock/mock.go index 50d2a431e018..1def436511a2 100644 --- a/x-pack/filebeat/input/gcs/mock/mock.go +++ b/x-pack/filebeat/input/gcs/mock/mock.go @@ -98,3 +98,43 @@ func GCSFileServer() http.Handler { w.Write([]byte("resource not found")) }) } + +//nolint:errcheck // We can ignore errors here, as this is just for testing +func GCSRetryServer() http.Handler { + retries := 0 + return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { + retries++ + path := strings.Split(strings.TrimLeft(r.URL.Path, "/"), "/") + if r.Method == http.MethodGet && retries >= 3 { + switch len(path) { + case 2: + if path[0] == "b" { + if buckets[path[1]] { + w.Write([]byte(fetchBucket[path[1]])) + return + } + } else if buckets[path[0]] && availableObjects[path[0]][path[1]] { + w.Write([]byte(objects[path[0]][path[1]])) + return + } + case 3: + if path[0] == "b" && path[2] == "o" { + if buckets[path[1]] { + w.Write([]byte(objectList[path[1]])) + return + } + } else if buckets[path[0]] { + objName := strings.Join(path[1:], "/") + if availableObjects[path[0]][objName] { + w.Write([]byte(objects[path[0]][objName])) + return + } + } + default: + w.WriteHeader(http.StatusNotFound) + return + } + } + w.WriteHeader(http.StatusInternalServerError) + }) +} diff --git a/x-pack/filebeat/input/gcs/types.go b/x-pack/filebeat/input/gcs/types.go index a34c7f7160ff..82fb737cdb65 100644 --- a/x-pack/filebeat/input/gcs/types.go +++ b/x-pack/filebeat/input/gcs/types.go @@ -22,6 +22,7 @@ type Source struct { FileSelectors []fileSelectorConfig ReaderConfig readerConfig ExpandEventListFromField string + Retry retryConfig } func (s *Source) Name() string { From 9c45417e78d0d7fd8764d8e66a6bc35ea8ac7df2 Mon Sep 17 00:00:00 2001 From: Lee E Hinman <57081003+leehinman@users.noreply.github.com> Date: Wed, 4 Dec 2024 13:02:51 -0600 Subject: [PATCH 15/48] add metricbeat benchmark module (#41801) * add metricbeat benchmark module --------- Co-authored-by: Shaunak Kashyap --- CHANGELOG.next.asciidoc | 1 + metricbeat/docs/fields.asciidoc | 31 ++++++++ metricbeat/docs/modules/benchmark.asciidoc | 76 +++++++++++++++++++ .../docs/modules/benchmark/info.asciidoc | 29 +++++++ metricbeat/docs/modules_list.asciidoc | 3 + x-pack/metricbeat/include/list.go | 2 + x-pack/metricbeat/metricbeat.reference.yml | 76 ++++++++++--------- .../module/benchmark/_meta/config.yml | 6 ++ .../module/benchmark/_meta/docs.asciidoc | 31 ++++++++ .../module/benchmark/_meta/fields.yml | 10 +++ x-pack/metricbeat/module/benchmark/doc.go | 6 ++ x-pack/metricbeat/module/benchmark/fields.go | 23 ++++++ .../module/benchmark/info/_meta/data.json | 23 ++++++ .../module/benchmark/info/_meta/docs.asciidoc | 1 + .../module/benchmark/info/_meta/fields.yml | 10 +++ .../module/benchmark/info/config.go | 24 ++++++ .../module/benchmark/info/config_test.go | 37 +++++++++ .../metricbeat/module/benchmark/info/info.go | 62 +++++++++++++++ .../module/benchmark/info/info_test.go | 54 +++++++++++++ .../modules.d/benchmark.yml.disabled | 9 +++ 20 files changed, 480 insertions(+), 34 deletions(-) create mode 100644 metricbeat/docs/modules/benchmark.asciidoc create mode 100644 metricbeat/docs/modules/benchmark/info.asciidoc create mode 100644 x-pack/metricbeat/module/benchmark/_meta/config.yml create mode 100644 x-pack/metricbeat/module/benchmark/_meta/docs.asciidoc create mode 100644 x-pack/metricbeat/module/benchmark/_meta/fields.yml create mode 100644 x-pack/metricbeat/module/benchmark/doc.go create mode 100644 x-pack/metricbeat/module/benchmark/fields.go create mode 100644 x-pack/metricbeat/module/benchmark/info/_meta/data.json create mode 100644 x-pack/metricbeat/module/benchmark/info/_meta/docs.asciidoc create mode 100644 x-pack/metricbeat/module/benchmark/info/_meta/fields.yml create mode 100644 x-pack/metricbeat/module/benchmark/info/config.go create mode 100644 x-pack/metricbeat/module/benchmark/info/config_test.go create mode 100644 x-pack/metricbeat/module/benchmark/info/info.go create mode 100644 x-pack/metricbeat/module/benchmark/info/info_test.go create mode 100644 x-pack/metricbeat/modules.d/benchmark.yml.disabled diff --git a/CHANGELOG.next.asciidoc b/CHANGELOG.next.asciidoc index 4ad010d29e27..8d5d060ac39a 100644 --- a/CHANGELOG.next.asciidoc +++ b/CHANGELOG.next.asciidoc @@ -408,6 +408,7 @@ https://github.com/elastic/beats/compare/v8.8.1\...main[Check the HEAD diff] - Add support for location label as an optional configuration parameter in GCP metrics metricset. {issue}41550[41550] {pull}41626[41626] *Metricbeat* +- Add benchmark module {pull}41801[41801] *Osquerybeat* diff --git a/metricbeat/docs/fields.asciidoc b/metricbeat/docs/fields.asciidoc index 09fd5e532450..5f9ee24aa8c0 100644 --- a/metricbeat/docs/fields.asciidoc +++ b/metricbeat/docs/fields.asciidoc @@ -23,6 +23,7 @@ grouped in the following categories: * <> * <> * <> +* <> * <> * <> * <> @@ -10472,6 +10473,36 @@ type: long -- +[[exported-fields-benchmark]] +== Benchmark fields + +benchmark module + + + +[float] +=== benchmark + + + + +[float] +=== info + +info + + + +*`benchmark.info.counter`*:: ++ +-- +The nth info metric emitted by the benchmark module + + +type: keyword + +-- + [[exported-fields-ceph]] == Ceph fields diff --git a/metricbeat/docs/modules/benchmark.asciidoc b/metricbeat/docs/modules/benchmark.asciidoc new file mode 100644 index 000000000000..01c950c84d41 --- /dev/null +++ b/metricbeat/docs/modules/benchmark.asciidoc @@ -0,0 +1,76 @@ +//// +This file is generated! See scripts/mage/docs_collector.go +//// + +:modulename: benchmark +:edit_url: https://github.com/elastic/beats/edit/main/x-pack/metricbeat/module/benchmark/_meta/docs.asciidoc + + +[[metricbeat-module-benchmark]] +[role="xpack"] +== Benchmark module + +beta[] + +include::{libbeat-dir}/shared/integration-link.asciidoc[] + +:modulename!: + +The `benchmark` module is used to generate synthetic metrics at a predictable rate. This can be useful when you want to test output settings or test system sizing without using real data. + +The `benchmark` module metricset is `info`. + +[source,yaml] +---- +- module: benchmark + metricsets: + - info + enabled: true + period: 10s +---- + +[float] +== Metricsets + +[float] +=== `info` +A metric that includes a `counter` field which is used to keep the metric unique. + +[float] +=== Module-specific configuration notes + +`count`:: number, the number of metrics to emit per fetch. + + + + + +:edit_url: + +[float] +=== Example configuration + +The Benchmark module supports the standard configuration options that are described +in <>. Here is an example configuration: + +[source,yaml] +---- +metricbeat.modules: +- module: benchmark + metricsets: + - info + enabled: false + period: 10s + +---- + +[float] +=== Metricsets + +The following metricsets are available: + +* <> + +include::benchmark/info.asciidoc[] + +:edit_url!: diff --git a/metricbeat/docs/modules/benchmark/info.asciidoc b/metricbeat/docs/modules/benchmark/info.asciidoc new file mode 100644 index 000000000000..4f6cee9874ff --- /dev/null +++ b/metricbeat/docs/modules/benchmark/info.asciidoc @@ -0,0 +1,29 @@ +//// +This file is generated! See scripts/mage/docs_collector.go +//// +:edit_url: https://github.com/elastic/beats/edit/main/x-pack/metricbeat/module/benchmark/info/_meta/docs.asciidoc + + +[[metricbeat-metricset-benchmark-info]] +[role="xpack"] +=== Benchmark info metricset + +beta[] + +include::../../../../x-pack/metricbeat/module/benchmark/info/_meta/docs.asciidoc[] + + +:edit_url: + +==== Fields + +For a description of each field in the metricset, see the +<> section. + +Here is an example document generated by this metricset: + +[source,json] +---- +include::../../../../x-pack/metricbeat/module/benchmark/info/_meta/data.json[] +---- +:edit_url!: \ No newline at end of file diff --git a/metricbeat/docs/modules_list.asciidoc b/metricbeat/docs/modules_list.asciidoc index f68dc8e1e65a..abf04650f2ca 100644 --- a/metricbeat/docs/modules_list.asciidoc +++ b/metricbeat/docs/modules_list.asciidoc @@ -51,6 +51,8 @@ This file is generated! See scripts/mage/docs_collector.go |<> |image:./images/icon-no.png[No prebuilt dashboards] | .2+| .2+| |<> |<> +|<> beta[] |image:./images/icon-no.png[No prebuilt dashboards] | +.1+| .1+| |<> beta[] |<> |image:./images/icon-yes.png[Prebuilt dashboards are available] | .13+| .13+| |<> |<> @@ -344,6 +346,7 @@ include::modules/aws.asciidoc[] include::modules/awsfargate.asciidoc[] include::modules/azure.asciidoc[] include::modules/beat.asciidoc[] +include::modules/benchmark.asciidoc[] include::modules/ceph.asciidoc[] include::modules/cloudfoundry.asciidoc[] include::modules/cockroachdb.asciidoc[] diff --git a/x-pack/metricbeat/include/list.go b/x-pack/metricbeat/include/list.go index 01ce86edf78c..b9b426cf0add 100644 --- a/x-pack/metricbeat/include/list.go +++ b/x-pack/metricbeat/include/list.go @@ -21,6 +21,8 @@ import ( _ "github.com/elastic/beats/v7/x-pack/metricbeat/module/azure/billing" _ "github.com/elastic/beats/v7/x-pack/metricbeat/module/azure/monitor" _ "github.com/elastic/beats/v7/x-pack/metricbeat/module/azure/storage" + _ "github.com/elastic/beats/v7/x-pack/metricbeat/module/benchmark" + _ "github.com/elastic/beats/v7/x-pack/metricbeat/module/benchmark/info" _ "github.com/elastic/beats/v7/x-pack/metricbeat/module/cloudfoundry" _ "github.com/elastic/beats/v7/x-pack/metricbeat/module/cloudfoundry/container" _ "github.com/elastic/beats/v7/x-pack/metricbeat/module/cloudfoundry/counter" diff --git a/x-pack/metricbeat/metricbeat.reference.yml b/x-pack/metricbeat/metricbeat.reference.yml index f7f048da84bd..8d3949ef666a 100644 --- a/x-pack/metricbeat/metricbeat.reference.yml +++ b/x-pack/metricbeat/metricbeat.reference.yml @@ -404,6 +404,14 @@ metricbeat.modules: # Monitoring instead of metricbeat-* indices. #xpack.enabled: false +#------------------------------ Benchmark Module ------------------------------ +- module: benchmark + metricsets: + - info + enabled: false + period: 10s + + #--------------------------------- Ceph Module --------------------------------- # Metricsets depending on the Ceph REST API (default port: 5000) - module: ceph @@ -1356,9 +1364,11 @@ metricbeat.modules: # Password to use when connecting to PostgreSQL. Empty by default. #password: pass -#----------------------- Prometheus Typed Metrics Module ----------------------- +#------------------------------ Prometheus Module ------------------------------ +# Metrics collected from a Prometheus endpoint - module: prometheus period: 10s + metricsets: ["collector"] hosts: ["localhost:9090"] metrics_path: /metrics #metrics_filters: @@ -1367,20 +1377,14 @@ metricbeat.modules: #username: "user" #password: "secret" + # Count number of metrics present in Elasticsearch document (default: false) + #metrics_count: false + # This can be used for service account based authorization: #bearer_token_file: /var/run/secrets/kubernetes.io/serviceaccount/token #ssl.certificate_authorities: # - /var/run/secrets/kubernetes.io/serviceaccount/service-ca.crt - # Count number of metrics present in Elasticsearch document (default: false) - #metrics_count: false - - # Use Elasticsearch histogram type to store histograms (beta, default: false) - # This will change the default layout and put metric type in the field name - #use_types: true - - # Store counter rates instead of original cumulative counters (experimental, default: false) - #rate_counters: true # Metrics sent by a Prometheus server using remote_write option #- module: prometheus @@ -1388,24 +1392,12 @@ metricbeat.modules: # host: "localhost" # port: "9201" - # Secure settings for the server using TLS/SSL: - #ssl.certificate: "/etc/pki/server/cert.pem" - #ssl.key: "/etc/pki/server/cert.key" - # Count number of metrics present in Elasticsearch document (default: false) #metrics_count: false - # Use Elasticsearch histogram type to store histograms (beta, default: false) - # This will change the default layout and put metric type in the field name - #use_types: true - - # Store counter rates instead of original cumulative counters (experimental, default: false) - #rate_counters: true - - # Define patterns for counter and histogram types so as to identify metrics' types according to these patterns - #types_patterns: - # counter_patterns: [] - # histogram_patterns: [] + # Secure settings for the server using TLS/SSL: + #ssl.certificate: "/etc/pki/server/cert.pem" + #ssl.key: "/etc/pki/server/cert.key" # Metrics that will be collected using a PromQL #- module: prometheus @@ -1433,11 +1425,9 @@ metricbeat.modules: # params: # query: "some_value" -#------------------------------ Prometheus Module ------------------------------ -# Metrics collected from a Prometheus endpoint +#----------------------- Prometheus Typed Metrics Module ----------------------- - module: prometheus period: 10s - metricsets: ["collector"] hosts: ["localhost:9090"] metrics_path: /metrics #metrics_filters: @@ -1446,14 +1436,20 @@ metricbeat.modules: #username: "user" #password: "secret" - # Count number of metrics present in Elasticsearch document (default: false) - #metrics_count: false - # This can be used for service account based authorization: #bearer_token_file: /var/run/secrets/kubernetes.io/serviceaccount/token #ssl.certificate_authorities: # - /var/run/secrets/kubernetes.io/serviceaccount/service-ca.crt + # Count number of metrics present in Elasticsearch document (default: false) + #metrics_count: false + + # Use Elasticsearch histogram type to store histograms (beta, default: false) + # This will change the default layout and put metric type in the field name + #use_types: true + + # Store counter rates instead of original cumulative counters (experimental, default: false) + #rate_counters: true # Metrics sent by a Prometheus server using remote_write option #- module: prometheus @@ -1461,13 +1457,25 @@ metricbeat.modules: # host: "localhost" # port: "9201" - # Count number of metrics present in Elasticsearch document (default: false) - #metrics_count: false - # Secure settings for the server using TLS/SSL: #ssl.certificate: "/etc/pki/server/cert.pem" #ssl.key: "/etc/pki/server/cert.key" + # Count number of metrics present in Elasticsearch document (default: false) + #metrics_count: false + + # Use Elasticsearch histogram type to store histograms (beta, default: false) + # This will change the default layout and put metric type in the field name + #use_types: true + + # Store counter rates instead of original cumulative counters (experimental, default: false) + #rate_counters: true + + # Define patterns for counter and histogram types so as to identify metrics' types according to these patterns + #types_patterns: + # counter_patterns: [] + # histogram_patterns: [] + # Metrics that will be collected using a PromQL #- module: prometheus # metricsets: ["query"] diff --git a/x-pack/metricbeat/module/benchmark/_meta/config.yml b/x-pack/metricbeat/module/benchmark/_meta/config.yml new file mode 100644 index 000000000000..535ce486754d --- /dev/null +++ b/x-pack/metricbeat/module/benchmark/_meta/config.yml @@ -0,0 +1,6 @@ +- module: benchmark + metricsets: + - info + enabled: false + period: 10s + diff --git a/x-pack/metricbeat/module/benchmark/_meta/docs.asciidoc b/x-pack/metricbeat/module/benchmark/_meta/docs.asciidoc new file mode 100644 index 000000000000..5b0dbf829fcc --- /dev/null +++ b/x-pack/metricbeat/module/benchmark/_meta/docs.asciidoc @@ -0,0 +1,31 @@ +include::{libbeat-dir}/shared/integration-link.asciidoc[] + +:modulename!: + +The `benchmark` module is used to generate synthetic metrics at a predictable rate. This can be useful when you want to test output settings or test system sizing without using real data. + +The `benchmark` module metricset is `info`. + +[source,yaml] +---- +- module: benchmark + metricsets: + - info + enabled: true + period: 10s +---- + +[float] +== Metricsets + +[float] +=== `info` +A metric that includes a `counter` field which is used to keep the metric unique. + +[float] +=== Module-specific configuration notes + +`count`:: number, the number of metrics to emit per fetch. + + + diff --git a/x-pack/metricbeat/module/benchmark/_meta/fields.yml b/x-pack/metricbeat/module/benchmark/_meta/fields.yml new file mode 100644 index 000000000000..308834cb5dc8 --- /dev/null +++ b/x-pack/metricbeat/module/benchmark/_meta/fields.yml @@ -0,0 +1,10 @@ +- key: benchmark + title: "Benchmark" + release: beta + description: > + benchmark module + fields: + - name: benchmark + type: group + description: > + fields: diff --git a/x-pack/metricbeat/module/benchmark/doc.go b/x-pack/metricbeat/module/benchmark/doc.go new file mode 100644 index 000000000000..461045f17c20 --- /dev/null +++ b/x-pack/metricbeat/module/benchmark/doc.go @@ -0,0 +1,6 @@ +// Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one +// or more contributor license agreements. Licensed under the Elastic License; +// you may not use this file except in compliance with the Elastic License. + +// Package benchmark is a Metricbeat module that contains MetricSets. +package benchmark diff --git a/x-pack/metricbeat/module/benchmark/fields.go b/x-pack/metricbeat/module/benchmark/fields.go new file mode 100644 index 000000000000..30fa60460d80 --- /dev/null +++ b/x-pack/metricbeat/module/benchmark/fields.go @@ -0,0 +1,23 @@ +// Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one +// or more contributor license agreements. Licensed under the Elastic License; +// you may not use this file except in compliance with the Elastic License. + +// Code generated by beats/dev-tools/cmd/asset/asset.go - DO NOT EDIT. + +package benchmark + +import ( + "github.com/elastic/beats/v7/libbeat/asset" +) + +func init() { + if err := asset.SetFields("metricbeat", "benchmark", asset.ModuleFieldsPri, AssetBenchmark); err != nil { + panic(err) + } +} + +// AssetBenchmark returns asset data. +// This is the base64 encoded zlib format compressed contents of module/benchmark. +func AssetBenchmark() string { + return "eJx8kM1txCAUhO9UMdr7NsAhh9SQBliYDcj8WPhZEd1HOHFiEyvf8Q36ZsQdE5vGg9n6ZOqkAAkSqXF73W83BVRGmoX9pRgFOC62hllCyRovCsCvA6m4NVIBz8DoFr3Fd2STeK7qSJup8V7LOn9fLtxn1VEX8rP8HK9snXH9zmXTF4N3rD9OsGXNwnrK9iUT20epbsj+6e28eSKL3zYgUWqwYAoidHg0iOffz/4MAAD//xhTfdM=" +} diff --git a/x-pack/metricbeat/module/benchmark/info/_meta/data.json b/x-pack/metricbeat/module/benchmark/info/_meta/data.json new file mode 100644 index 000000000000..a64b394dfd98 --- /dev/null +++ b/x-pack/metricbeat/module/benchmark/info/_meta/data.json @@ -0,0 +1,23 @@ +{ + "@timestamp": "2016-05-23T08:05:34.853Z", + "metricset": { + "name": "info", + "period": 1000 + }, + "event": { + "duration": 27000, + "dataset": "benchmark.info", + "module": "benchmark" + }, + "service": { + "type": "benchmark" + }, + "service": { + "type": "benchmark" + }, + "benchmark": { + "info": { + "counter": 42 + } + } +} diff --git a/x-pack/metricbeat/module/benchmark/info/_meta/docs.asciidoc b/x-pack/metricbeat/module/benchmark/info/_meta/docs.asciidoc new file mode 100644 index 000000000000..a8f407cf7f39 --- /dev/null +++ b/x-pack/metricbeat/module/benchmark/info/_meta/docs.asciidoc @@ -0,0 +1 @@ +This is the info metricset of the module benchmark. diff --git a/x-pack/metricbeat/module/benchmark/info/_meta/fields.yml b/x-pack/metricbeat/module/benchmark/info/_meta/fields.yml new file mode 100644 index 000000000000..0068b75bcf0f --- /dev/null +++ b/x-pack/metricbeat/module/benchmark/info/_meta/fields.yml @@ -0,0 +1,10 @@ +- name: info + type: group + release: beta + description: > + info + fields: + - name: counter + type: keyword + description: > + The nth info metric emitted by the benchmark module diff --git a/x-pack/metricbeat/module/benchmark/info/config.go b/x-pack/metricbeat/module/benchmark/info/config.go new file mode 100644 index 000000000000..424a8a5c60c2 --- /dev/null +++ b/x-pack/metricbeat/module/benchmark/info/config.go @@ -0,0 +1,24 @@ +// Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one +// or more contributor license agreements. Licensed under the Elastic License; +// you may not use this file except in compliance with the Elastic License. + +package info + +import ( + "errors" +) + +type infoConfig struct { + Count uint `config:"count"` +} + +var defaultConfig = infoConfig{ + Count: 1, +} + +func (c *infoConfig) Validate() error { + if c.Count == 0 { + return errors.New("benchmark module 'count' must be greater than 0") + } + return nil +} diff --git a/x-pack/metricbeat/module/benchmark/info/config_test.go b/x-pack/metricbeat/module/benchmark/info/config_test.go new file mode 100644 index 000000000000..95030443b017 --- /dev/null +++ b/x-pack/metricbeat/module/benchmark/info/config_test.go @@ -0,0 +1,37 @@ +// Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one +// or more contributor license agreements. Licensed under the Elastic License; +// you may not use this file except in compliance with the Elastic License. + +package info + +import ( + "strings" + "testing" +) + +func TestValidate(t *testing.T) { + tests := map[string]struct { + cfg infoConfig + expectError bool + errorString string + }{ + "default": {cfg: defaultConfig}, + "empty": {cfg: infoConfig{}, expectError: true, errorString: "benchmark module 'count' must be greater than 0"}, + "counter 0": {cfg: infoConfig{Count: 0}, expectError: true, errorString: "benchmark module 'count' must be greater than 0"}, + } + + for name, tc := range tests { + t.Run(name, func(t *testing.T) { + err := tc.cfg.Validate() + if err == nil && tc.expectError == true { + t.Fatalf("expected validation error, didn't get it") + } + if err != nil && tc.expectError == false { + t.Fatalf("unexpected validation error: %s", err) + } + if err != nil && !strings.Contains(err.Error(), tc.errorString) { + t.Fatalf("error: '%s' didn't contain expected string: '%s'", err, tc.errorString) + } + }) + } +} diff --git a/x-pack/metricbeat/module/benchmark/info/info.go b/x-pack/metricbeat/module/benchmark/info/info.go new file mode 100644 index 000000000000..bd4ca1e6272a --- /dev/null +++ b/x-pack/metricbeat/module/benchmark/info/info.go @@ -0,0 +1,62 @@ +// Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one +// or more contributor license agreements. Licensed under the Elastic License; +// you may not use this file except in compliance with the Elastic License. + +package info + +import ( + "github.com/elastic/beats/v7/libbeat/common/cfgwarn" + "github.com/elastic/beats/v7/metricbeat/mb" + "github.com/elastic/elastic-agent-libs/mapstr" +) + +// init registers the MetricSet with the central registry as soon as the program +// starts. The New function will be called later to instantiate an instance of +// the MetricSet for each host is defined in the module's configuration. After the +// MetricSet has been created then Fetch will begin to be called periodically. +func init() { + mb.Registry.MustAddMetricSet("benchmark", "info", New) +} + +// MetricSet holds any configuration or state information. It must implement +// the mb.MetricSet interface. And this is best achieved by embedding +// mb.BaseMetricSet because it implements all of the required mb.MetricSet +// interface methods except for Fetch. +type MetricSet struct { + mb.BaseMetricSet + counter uint + eventsPerFetch uint +} + +// New creates a new instance of the MetricSet. New is responsible for unpacking +// any MetricSet specific configuration options if there are any. +func New(base mb.BaseMetricSet) (mb.MetricSet, error) { + cfgwarn.Beta("The benchmark info metricset is beta.") + + config := defaultConfig + if err := base.Module().UnpackConfig(&config); err != nil { + return nil, err + } + + return &MetricSet{ + BaseMetricSet: base, + counter: 1, + eventsPerFetch: config.Count, + }, nil +} + +// Fetch method implements the data gathering and data conversion to the right +// format. It publishes the event which is then forwarded to the output. In case +// of an error set the Error field of mb.Event or simply call report.Error(). +func (m *MetricSet) Fetch(report mb.ReporterV2) error { + for i := uint(0); i < m.eventsPerFetch; i++ { + report.Event(mb.Event{ + MetricSetFields: mapstr.M{ + "counter": m.counter, + }, + }) + m.counter++ + } + + return nil +} diff --git a/x-pack/metricbeat/module/benchmark/info/info_test.go b/x-pack/metricbeat/module/benchmark/info/info_test.go new file mode 100644 index 000000000000..1df775e76b01 --- /dev/null +++ b/x-pack/metricbeat/module/benchmark/info/info_test.go @@ -0,0 +1,54 @@ +// Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one +// or more contributor license agreements. Licensed under the Elastic License; +// you may not use this file except in compliance with the Elastic License. + +package info + +import ( + "testing" + + "github.com/stretchr/testify/assert" + + mbtest "github.com/elastic/beats/v7/metricbeat/mb/testing" +) + +func TestFetch(t *testing.T) { + tests := map[string]struct { + count uint + }{ + "one count": {count: uint(1)}, + "five count": {count: uint(5)}, + } + for name, tc := range tests { + t.Run(name, func(t *testing.T) { + config := map[string]interface{}{ + "module": "benchmark", + "period": "1s", + "metricsets": []string{"info"}, + "count": tc.count, + } + t.Cleanup(func() { + if t.Failed() { + t.Logf("Contents of config:\n%v", config) + } + }) + + f := mbtest.NewFetcher(t, config) + events, errs := f.FetchEvents() + assert.Emptyf(t, errs, "errs should be empty, err: %v", errs) + assert.Equalf(t, int(tc.count), len(events), "events should have %d events not %d, events: %v", int(tc.count), len(events), events) + + for i, event := range events { + msf := event.MetricSetFields + + ok, err := msf.HasKey("counter") + assert.Truef(t, ok, "MetricSetFields must contain \"counter\", msf: %v", msf) + assert.NoErrorf(t, err, "MetricSetFields must contain \"counter\", msf: %v", msf) + + v, err := msf.GetValue("counter") + assert.NoErrorf(t, err, "MetricSetFields must contain \"counter\", msf: %v", msf) + assert.Equalf(t, uint(i+1), v, "counter should be %d, was %v", i+1, v) + } + }) + } +} diff --git a/x-pack/metricbeat/modules.d/benchmark.yml.disabled b/x-pack/metricbeat/modules.d/benchmark.yml.disabled new file mode 100644 index 000000000000..29901546c423 --- /dev/null +++ b/x-pack/metricbeat/modules.d/benchmark.yml.disabled @@ -0,0 +1,9 @@ +# Module: benchmark +# Docs: https://www.elastic.co/guide/en/beats/metricbeat/main/metricbeat-module-benchmark.html + +- module: benchmark + metricsets: + - info + enabled: false + period: 10s + From 15d189d957f15a4b5d1d9d42586515684daa6fd1 Mon Sep 17 00:00:00 2001 From: "mergify[bot]" <37929162+mergify[bot]@users.noreply.github.com> Date: Wed, 4 Dec 2024 18:01:44 -0500 Subject: [PATCH 16/48] Add known issues for Filebeat 8.14.0 (#41882) (#41897) (cherry picked from commit 0810a24128aeb47110acb66c61a691024844f674) Co-authored-by: Tiago Queiroz --- CHANGELOG.asciidoc | 20 ++++++++++++++++++++ 1 file changed, 20 insertions(+) diff --git a/CHANGELOG.asciidoc b/CHANGELOG.asciidoc index 140a231e2c86..21a0639b1e6f 100644 --- a/CHANGELOG.asciidoc +++ b/CHANGELOG.asciidoc @@ -441,6 +441,11 @@ filebeat.inputs: === Beats version 8.14.3 https://github.com/elastic/beats/compare/v8.14.2\...v8.14.3[View commits] +==== Known Issues + +*Filebeat* + - Filestream input will resend files that have been inactive for 30min or more. Workaround: set `clean_inactive` to a very high value, like 5 years: `clean_inactive: 43800h0m0s`. {issue}40178[40178] + ==== Bugfixes *Filebeat* @@ -471,6 +476,11 @@ https://github.com/elastic/beats/compare/v8.14.2\...v8.14.3[View commits] === Beats version 8.14.2 https://github.com/elastic/beats/compare/v8.14.1\...v8.14.2[View commits] +==== Known Issues + +*Filebeat* + - Filestream input will resend files that have been inactive for 30min or more. Workaround: set `clean_inactive` to a very high value, like 5 years: `clean_inactive: 43800h0m0s`. {issue}40178[40178] + ==== Breaking changes *Filebeat* @@ -507,6 +517,11 @@ https://github.com/elastic/beats/compare/v8.14.1\...v8.14.2[View commits] === Beats version 8.14.1 https://github.com/elastic/beats/compare/v8.14.0\...v8.14.1[View commits] +==== Known Issues + +*Filebeat* + - Filestream input will resend files that have been inactive for 30min or more. Workaround: set `clean_inactive` to a very high value, like 5 years: `clean_inactive: 43800h0m0s`. {issue}40178[40178] + ==== Bugfixes *Heartbeat* @@ -518,6 +533,11 @@ https://github.com/elastic/beats/compare/v8.14.0\...v8.14.1[View commits] === Beats version 8.14.0 https://github.com/elastic/beats/compare/v8.13.4\...v8.14.0[View commits] +==== Known Issues + +*Filebeat* + - Filestream input will resend files that have been inactive for 30min or more. Workaround: set `clean_inactive` to a very high value, like 5 years: `clean_inactive: 43800h0m0s`. {issue}40178[40178] + ==== Breaking changes *Filebeat* From c51c8ce7070e43955e6fa253ef69f7c8e7772069 Mon Sep 17 00:00:00 2001 From: Marc Guasch Date: Thu, 5 Dec 2024 09:48:14 +0100 Subject: [PATCH 17/48] Make experimental api GA (#41770) --- CHANGELOG.next.asciidoc | 1 + winlogbeat/_meta/fields.common.yml | 4 +- winlogbeat/docs/fields.asciidoc | 2 +- winlogbeat/docs/winlogbeat-options.asciidoc | 12 ++--- ...log_experimental.go => wineventlog_raw.go} | 47 +++++++++--------- winlogbeat/eventlog/wineventlog_test.go | 12 ++--- winlogbeat/include/fields.go | 2 +- .../testdata/{experimental.evtx => raw.evtx} | Bin .../testdata/{experimental.xml => raw.xml} | 0 .../wineventlog/wineventlog_windows_test.go | 14 +++--- 10 files changed, 46 insertions(+), 48 deletions(-) rename winlogbeat/eventlog/{wineventlog_experimental.go => wineventlog_raw.go} (88%) rename winlogbeat/sys/wineventlog/testdata/{experimental.evtx => raw.evtx} (100%) rename winlogbeat/sys/wineventlog/testdata/{experimental.xml => raw.xml} (100%) diff --git a/CHANGELOG.next.asciidoc b/CHANGELOG.next.asciidoc index 8d5d060ac39a..c9cc72ebe739 100644 --- a/CHANGELOG.next.asciidoc +++ b/CHANGELOG.next.asciidoc @@ -427,6 +427,7 @@ https://github.com/elastic/beats/compare/v8.8.1\...main[Check the HEAD diff] - Language setting also added to decode xml wineventlog processor {pull}41525[41525] - Format embedded messages in the experimental api {pull}41525[41525] - Implement exclusion range support for event_id. {issue}38623[38623] {pull}41639[41639] +- Make the experimental API GA and rename it to winlogbeat-raw {issue}39580[39580] {pull}41770[41770] *Functionbeat* diff --git a/winlogbeat/_meta/fields.common.yml b/winlogbeat/_meta/fields.common.yml index ba2af74bb148..c1bef43568ec 100644 --- a/winlogbeat/_meta/fields.common.yml +++ b/winlogbeat/_meta/fields.common.yml @@ -27,8 +27,8 @@ required: true description: > The event log API type used to read the record. The possible values are - "wineventlog" for the Windows Event Log API or "wineventlog-experimental" for its - experimental implementation. + "wineventlog" for the Windows Event Log XML reader or "wineventlog-raw" for its + more performant implementation. - name: activity_id type: keyword diff --git a/winlogbeat/docs/fields.asciidoc b/winlogbeat/docs/fields.asciidoc index 567a78e4a911..c669e55bd3e8 100644 --- a/winlogbeat/docs/fields.asciidoc +++ b/winlogbeat/docs/fields.asciidoc @@ -16282,7 +16282,7 @@ All fields specific to the Windows Event Log are defined here. *`winlog.api`*:: + -- -The event log API type used to read the record. The possible values are "wineventlog" for the Windows Event Log API or "wineventlog-experimental" for its experimental implementation. +The event log API type used to read the record. The possible values are "wineventlog" for the Windows Event Log XML reader or "wineventlog-raw" for its more performant implementation. required: True diff --git a/winlogbeat/docs/winlogbeat-options.asciidoc b/winlogbeat/docs/winlogbeat-options.asciidoc index 1a68787dade9..1702561a7a66 100644 --- a/winlogbeat/docs/winlogbeat-options.asciidoc +++ b/winlogbeat/docs/winlogbeat-options.asciidoc @@ -500,21 +500,17 @@ example of how to read from an `.evtx` file in the <>. ==== `event_logs.api` This selects the event log reader implementation that is used to read events -from the Windows APIs. You should only set this option when testing experimental -features. When the value is set to `wineventlog-experimental` Winlogbeat will -replace the default event log reader with the **experimental** implementation. -We are evaluating this implementation to see if it can provide increased -performance and reduce CPU usage. *{vista_and_newer}* +from the Windows APIs. When the value is set to `wineventlog-raw` Winlogbeat will +replace the default XML event log reader with a more performant implementation. +*{vista_and_newer}* [source,yaml] -------------------------------------------------------------------------------- winlogbeat.event_logs: - name: ForwardedEvents - api: wineventlog-experimental + api: wineventlog-raw -------------------------------------------------------------------------------- -There are a few notable differences in the events: - * If `include_xml` is `true` the performance will be the same as the default API, as performance improvements are lost when parsing the XML. diff --git a/winlogbeat/eventlog/wineventlog_experimental.go b/winlogbeat/eventlog/wineventlog_raw.go similarity index 88% rename from winlogbeat/eventlog/wineventlog_experimental.go rename to winlogbeat/eventlog/wineventlog_raw.go index 580adb1cfe20..7a6917e9b7ad 100644 --- a/winlogbeat/eventlog/wineventlog_experimental.go +++ b/winlogbeat/eventlog/wineventlog_raw.go @@ -28,7 +28,6 @@ import ( "go.uber.org/multierr" "golang.org/x/sys/windows" - "github.com/elastic/beats/v7/libbeat/common/cfgwarn" "github.com/elastic/beats/v7/winlogbeat/checkpoint" win "github.com/elastic/beats/v7/winlogbeat/sys/wineventlog" conf "github.com/elastic/elastic-agent-libs/config" @@ -39,19 +38,23 @@ const ( // winEventLogExpApiName is the name used to identify the Windows Event Log API // as both an event type and an API. winEventLogExpAPIName = "wineventlog-experimental" + // winEventLogRawAPIName is the name used to identify the Windows Event Log API + // as both an event type and an API. + winEventLogRawAPIName = "wineventlog-raw" ) func init() { // Register wineventlog API if it is available. available, _ := win.IsAvailable() if available { - Register(winEventLogExpAPIName, 10, newWinEventLogExp, win.Channels) + Register(winEventLogExpAPIName, 10, newWinEventLogRaw, win.Channels) + Register(winEventLogRawAPIName, 11, newWinEventLogRaw, win.Channels) } } -// winEventLogExp implements the EventLog interface for reading from the Windows +// winEventLogRaw implements the EventLog interface for reading from the Windows // Event Log API. -type winEventLogExp struct { +type winEventLogRaw struct { config winEventLogConfig query string id string // Identifier of this event log. @@ -67,16 +70,14 @@ type winEventLogExp struct { metrics *inputMetrics } -// newWinEventLogExp creates and returns a new EventLog for reading event logs +// newWinEventLogRaw creates and returns a new EventLog for reading event logs // using the Windows Event Log. -func newWinEventLogExp(options *conf.C) (EventLog, error) { +func newWinEventLogRaw(options *conf.C) (EventLog, error) { var xmlQuery string var err error var isFile bool var log *logp.Logger - cfgwarn.Experimental("The %s event log reader is experimental.", winEventLogExpAPIName) - c := winEventLogConfig{BatchReadSize: 512} if err := readConfig(options, &c); err != nil { return nil, err @@ -115,7 +116,7 @@ func newWinEventLogExp(options *conf.C) (EventLog, error) { log = logp.NewLogger("wineventlog").With("id", id).With("channel", c.Name) } - l := &winEventLogExp{ + l := &winEventLogRaw{ config: c, query: xmlQuery, id: id, @@ -148,27 +149,27 @@ func newWinEventLogExp(options *conf.C) (EventLog, error) { return l, nil } -func (l *winEventLogExp) isForwarded() bool { +func (l *winEventLogRaw) isForwarded() bool { c := l.config return (c.Forwarded != nil && *c.Forwarded) || (c.Forwarded == nil && c.Name == "ForwardedEvents") } // Name returns the name of the event log (i.e. Application, Security, etc.). -func (l *winEventLogExp) Name() string { +func (l *winEventLogRaw) Name() string { return l.id } // Channel returns the event log's channel name. -func (l *winEventLogExp) Channel() string { +func (l *winEventLogRaw) Channel() string { return l.channelName } // IsFile returns true if the event log is an evtx file. -func (l *winEventLogExp) IsFile() bool { +func (l *winEventLogRaw) IsFile() bool { return l.file } -func (l *winEventLogExp) Open(state checkpoint.EventLogState) error { +func (l *winEventLogRaw) Open(state checkpoint.EventLogState) error { l.lastRead = state // we need to defer metrics initialization since when the event log // is used from winlog input it would register it twice due to CheckConfig calls @@ -185,7 +186,7 @@ func (l *winEventLogExp) Open(state checkpoint.EventLogState) error { return err } -func (l *winEventLogExp) open(state checkpoint.EventLogState) (win.EvtHandle, error) { +func (l *winEventLogRaw) open(state checkpoint.EventLogState) (win.EvtHandle, error) { var bookmark win.Bookmark if len(state.Bookmark) > 0 { var err error @@ -202,7 +203,7 @@ func (l *winEventLogExp) open(state checkpoint.EventLogState) (win.EvtHandle, er return l.openChannel(bookmark) } -func (l *winEventLogExp) openFile(state checkpoint.EventLogState, bookmark win.Bookmark) (win.EvtHandle, error) { +func (l *winEventLogRaw) openFile(state checkpoint.EventLogState, bookmark win.Bookmark) (win.EvtHandle, error) { path := l.channelName h, err := win.EvtQuery(0, path, l.query, win.EvtQueryFilePath|win.EvtQueryForwardDirection) @@ -239,7 +240,7 @@ func (l *winEventLogExp) openFile(state checkpoint.EventLogState, bookmark win.B return h, err } -func (l *winEventLogExp) openChannel(bookmark win.Bookmark) (win.EvtHandle, error) { +func (l *winEventLogRaw) openChannel(bookmark win.Bookmark) (win.EvtHandle, error) { // Using a pull subscription to receive events. See: // https://msdn.microsoft.com/en-us/library/windows/desktop/aa385771(v=vs.85).aspx#pull signalEvent, err := windows.CreateEvent(nil, 0, 0, nil) @@ -281,7 +282,7 @@ func (l *winEventLogExp) openChannel(bookmark win.Bookmark) (win.EvtHandle, erro } } -func (l *winEventLogExp) Read() ([]Record, error) { +func (l *winEventLogRaw) Read() ([]Record, error) { //nolint:prealloc // Avoid unnecessary preallocation for each reader every second when event log is inactive. var records []Record defer func() { @@ -319,7 +320,7 @@ func (l *winEventLogExp) Read() ([]Record, error) { return records, nil } -func (l *winEventLogExp) processHandle(h win.EvtHandle) (*Record, error) { +func (l *winEventLogRaw) processHandle(h win.EvtHandle) (*Record, error) { defer h.Close() // NOTE: Render can return an error and a partial event. @@ -357,7 +358,7 @@ func (l *winEventLogExp) processHandle(h win.EvtHandle) (*Record, error) { return r, nil } -func (l *winEventLogExp) createBookmarkFromEvent(evtHandle win.EvtHandle) (string, error) { +func (l *winEventLogRaw) createBookmarkFromEvent(evtHandle win.EvtHandle) (string, error) { bookmark, err := win.NewBookmarkFromEvent(evtHandle) if err != nil { return "", fmt.Errorf("failed to create new bookmark from event handle: %w", err) @@ -367,18 +368,18 @@ func (l *winEventLogExp) createBookmarkFromEvent(evtHandle win.EvtHandle) (strin return bookmark.XML() } -func (l *winEventLogExp) Reset() error { +func (l *winEventLogRaw) Reset() error { l.log.Debug("Closing event log reader handles for reset.") return l.close() } -func (l *winEventLogExp) Close() error { +func (l *winEventLogRaw) Close() error { l.log.Debug("Closing event log reader handles.") l.metrics.close() return l.close() } -func (l *winEventLogExp) close() error { +func (l *winEventLogRaw) close() error { if l.iterator == nil { return l.renderer.Close() } diff --git a/winlogbeat/eventlog/wineventlog_test.go b/winlogbeat/eventlog/wineventlog_test.go index 3277bb5d7f1c..9aafe31a258d 100644 --- a/winlogbeat/eventlog/wineventlog_test.go +++ b/winlogbeat/eventlog/wineventlog_test.go @@ -170,11 +170,11 @@ func TestWindowsEventLogAPI(t *testing.T) { testWindowsEventLog(t, winEventLogAPIName, false) } -func TestWindowsEventLogAPIExperimental(t *testing.T) { - // for the experimental api using include xml behave differently than not +func TestWindowsEventLogAPIRaw(t *testing.T) { + // for the raw api using include xml behave differently than not // so we must test both settings - testWindowsEventLog(t, winEventLogExpAPIName, true) - testWindowsEventLog(t, winEventLogExpAPIName, false) + testWindowsEventLog(t, winEventLogRawAPIName, true) + testWindowsEventLog(t, winEventLogRawAPIName, false) } func testWindowsEventLog(t *testing.T, api string, includeXML bool) { @@ -407,8 +407,8 @@ func openLog(t testing.TB, api string, state *checkpoint.EventLogState, config m switch api { case winEventLogAPIName: log, err = newWinEventLog(cfg) - case winEventLogExpAPIName: - log, err = newWinEventLogExp(cfg) + case winEventLogRawAPIName: + log, err = newWinEventLogRaw(cfg) default: t.Fatalf("Unknown API name: '%s'", api) } diff --git a/winlogbeat/include/fields.go b/winlogbeat/include/fields.go index b40185bdf54c..e372ca95ed2e 100644 --- a/winlogbeat/include/fields.go +++ b/winlogbeat/include/fields.go @@ -32,5 +32,5 @@ func init() { // AssetBuildFieldsFieldsCommonYml returns asset data. // This is the base64 encoded zlib format compressed contents of build/fields/fields.common.yml. func AssetBuildFieldsFieldsCommonYml() string { - return "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" + return "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" } diff --git a/winlogbeat/sys/wineventlog/testdata/experimental.evtx b/winlogbeat/sys/wineventlog/testdata/raw.evtx similarity index 100% rename from winlogbeat/sys/wineventlog/testdata/experimental.evtx rename to winlogbeat/sys/wineventlog/testdata/raw.evtx diff --git a/winlogbeat/sys/wineventlog/testdata/experimental.xml b/winlogbeat/sys/wineventlog/testdata/raw.xml similarity index 100% rename from winlogbeat/sys/wineventlog/testdata/experimental.xml rename to winlogbeat/sys/wineventlog/testdata/raw.xml diff --git a/winlogbeat/sys/wineventlog/wineventlog_windows_test.go b/winlogbeat/sys/wineventlog/wineventlog_windows_test.go index e6b494e3b242..8c23098cd3a8 100644 --- a/winlogbeat/sys/wineventlog/wineventlog_windows_test.go +++ b/winlogbeat/sys/wineventlog/wineventlog_windows_test.go @@ -44,13 +44,13 @@ func TestWinEventLog(t *testing.T) { }{ {path: "application-windows-error-reporting.evtx", events: 1}, {path: "sysmon-9.01.evtx", events: 32}, - {path: "ec1.evtx", events: 1}, // eventcreate /id 1000 /t error /l application /d "My custom error event for the application log" - {path: "ec2.evtx", events: 1}, // eventcreate /id 999 /t error /l application /so WinWord /d "Winword event 999 happened due to low diskspace" - {path: "ec3.evtx", events: 1}, // eventcreate /id 5 /t error /l system /d "Catastrophe!" - {path: "ec4.evtx", events: 1}, // eventcreate /id 5 /t error /l system /so Backup /d "Backup failure" - {path: "ec3and4.evtx", events: 2}, // ec3 and ec3 exported as a single evtx. - {path: "original.evtx", events: 5}, // a capture from a short generation of the eventlog WindowsEventLogAPI test. - {path: "experimental.evtx", events: 5}, // a capture from a short generation of the eventlog WindowsEventLogAPIExperimental test. + {path: "ec1.evtx", events: 1}, // eventcreate /id 1000 /t error /l application /d "My custom error event for the application log" + {path: "ec2.evtx", events: 1}, // eventcreate /id 999 /t error /l application /so WinWord /d "Winword event 999 happened due to low diskspace" + {path: "ec3.evtx", events: 1}, // eventcreate /id 5 /t error /l system /d "Catastrophe!" + {path: "ec4.evtx", events: 1}, // eventcreate /id 5 /t error /l system /so Backup /d "Backup failure" + {path: "ec3and4.evtx", events: 2}, // ec3 and ec3 exported as a single evtx. + {path: "original.evtx", events: 5}, // a capture from a short generation of the eventlog WindowsEventLogAPI test. + {path: "raw.evtx", events: 5}, // a capture from a short generation of the eventlog WindowsEventLogAPIRaw test. } { t.Run(test.path, func(t *testing.T) { evtx, err := filepath.Abs(filepath.Join("testdata", test.path)) From 4e19d09ab2e7c908f16b0d9bed1eee994ee8c744 Mon Sep 17 00:00:00 2001 From: Chris Berkhout Date: Thu, 5 Dec 2024 09:58:22 +0100 Subject: [PATCH 18/48] x-pack/filebeat/input/entityanalytics/provider/okta: Rate limiting fixes (#41583) - Separate rate limits by endpoint. - Stop requests until reset when `x-rate-limit-remaining: 0`. --- CHANGELOG.next.asciidoc | 1 + .../provider/okta/internal/okta/okta.go | 148 +++++++----------- .../provider/okta/internal/okta/okta_test.go | 37 +++-- .../okta/internal/okta/ratelimiter.go | 97 ++++++++++++ .../okta/internal/okta/ratelimiter_test.go | 84 ++++++++++ .../entityanalytics/provider/okta/okta.go | 5 +- .../provider/okta/okta_test.go | 4 +- 7 files changed, 264 insertions(+), 112 deletions(-) create mode 100644 x-pack/filebeat/input/entityanalytics/provider/okta/internal/okta/ratelimiter.go create mode 100644 x-pack/filebeat/input/entityanalytics/provider/okta/internal/okta/ratelimiter_test.go diff --git a/CHANGELOG.next.asciidoc b/CHANGELOG.next.asciidoc index c9cc72ebe739..fc83979c1734 100644 --- a/CHANGELOG.next.asciidoc +++ b/CHANGELOG.next.asciidoc @@ -187,6 +187,7 @@ https://github.com/elastic/beats/compare/v8.8.1\...main[Check the HEAD diff] - Fix missing key in streaming input logging. {pull}41600[41600] - Improve S3 object size metric calculation to support situations where Content-Length is not available. {pull}41755[41755] - Fix handling of http_endpoint request exceeding memory limits. {issue}41764[41764] {pull}41765[41765] +- Rate limiting fixes in the Okta provider of the Entity Analytics input. {issue}40106[40106] {pull}41583[41583] *Heartbeat* diff --git a/x-pack/filebeat/input/entityanalytics/provider/okta/internal/okta/okta.go b/x-pack/filebeat/input/entityanalytics/provider/okta/internal/okta/okta.go index 3d8bdae11c97..42ffc0601784 100644 --- a/x-pack/filebeat/input/entityanalytics/provider/okta/internal/okta/okta.go +++ b/x-pack/filebeat/input/entityanalytics/provider/okta/internal/okta/okta.go @@ -14,13 +14,9 @@ import ( "io" "net/http" "net/url" - "path" - "strconv" "strings" "time" - "golang.org/x/time/rate" - "github.com/elastic/elastic-agent-libs/logp" ) @@ -195,16 +191,23 @@ func (o Response) String() string { // https://${yourOktaDomain}/reports/rate-limit. // // See https://developer.okta.com/docs/reference/api/users/#list-users for details. -func GetUserDetails(ctx context.Context, cli *http.Client, host, key, user string, query url.Values, omit Response, lim *rate.Limiter, window time.Duration, log *logp.Logger) ([]User, http.Header, error) { - const endpoint = "/api/v1/users" +func GetUserDetails(ctx context.Context, cli *http.Client, host, key, user string, query url.Values, omit Response, lim RateLimiter, window time.Duration, log *logp.Logger) ([]User, http.Header, error) { + var endpoint, path string + if user == "" { + endpoint = "/api/v1/users" + path = endpoint + } else { + endpoint = "/api/v1/users/{user}" + path = strings.Replace(endpoint, "{user}", user, 1) + } u := &url.URL{ Scheme: "https", Host: host, - Path: path.Join(endpoint, user), + Path: path, RawQuery: query.Encode(), } - return getDetails[User](ctx, cli, u, key, user == "", omit, lim, window, log) + return getDetails[User](ctx, cli, u, endpoint, key, user == "", omit, lim, window, log) } // GetUserFactors returns Okta group roles using the groups API endpoint. host is the @@ -213,19 +216,20 @@ func GetUserDetails(ctx context.Context, cli *http.Client, host, key, user strin // See GetUserDetails for details of the query and rate limit parameters. // // See https://developer.okta.com/docs/api/openapi/okta-management/management/tag/UserFactor/#tag/UserFactor/operation/listFactors. -func GetUserFactors(ctx context.Context, cli *http.Client, host, key, user string, lim *rate.Limiter, window time.Duration, log *logp.Logger) ([]Factor, http.Header, error) { - const endpoint = "/api/v1/users" - +func GetUserFactors(ctx context.Context, cli *http.Client, host, key, user string, lim RateLimiter, window time.Duration, log *logp.Logger) ([]Factor, http.Header, error) { if user == "" { return nil, nil, errors.New("no user specified") } + const endpoint = "/api/v1/users/{user}/factors" + path := strings.Replace(endpoint, "{user}", user, 1) + u := &url.URL{ Scheme: "https", Host: host, - Path: path.Join(endpoint, user, "factors"), + Path: path, } - return getDetails[Factor](ctx, cli, u, key, true, OmitNone, lim, window, log) + return getDetails[Factor](ctx, cli, u, endpoint, key, true, OmitNone, lim, window, log) } // GetUserRoles returns Okta group roles using the groups API endpoint. host is the @@ -234,19 +238,20 @@ func GetUserFactors(ctx context.Context, cli *http.Client, host, key, user strin // See GetUserDetails for details of the query and rate limit parameters. // // See https://developer.okta.com/docs/api/openapi/okta-management/management/tag/RoleAssignmentBGroup/#tag/RoleAssignmentBGroup/operation/listGroupAssignedRoles. -func GetUserRoles(ctx context.Context, cli *http.Client, host, key, user string, lim *rate.Limiter, window time.Duration, log *logp.Logger) ([]Role, http.Header, error) { - const endpoint = "/api/v1/users" - +func GetUserRoles(ctx context.Context, cli *http.Client, host, key, user string, lim RateLimiter, window time.Duration, log *logp.Logger) ([]Role, http.Header, error) { if user == "" { return nil, nil, errors.New("no user specified") } + const endpoint = "/api/v1/users/{user}/roles" + path := strings.Replace(endpoint, "{user}", user, 1) + u := &url.URL{ Scheme: "https", Host: host, - Path: path.Join(endpoint, user, "roles"), + Path: path, } - return getDetails[Role](ctx, cli, u, key, true, OmitNone, lim, window, log) + return getDetails[Role](ctx, cli, u, endpoint, key, true, OmitNone, lim, window, log) } // GetUserGroupDetails returns Okta group details using the users API endpoint. host is the @@ -255,19 +260,20 @@ func GetUserRoles(ctx context.Context, cli *http.Client, host, key, user string, // See GetUserDetails for details of the query and rate limit parameters. // // See https://developer.okta.com/docs/reference/api/users/#request-parameters-8 (no anchor exists on the page for this endpoint) for details. -func GetUserGroupDetails(ctx context.Context, cli *http.Client, host, key, user string, lim *rate.Limiter, window time.Duration, log *logp.Logger) ([]Group, http.Header, error) { - const endpoint = "/api/v1/users" - +func GetUserGroupDetails(ctx context.Context, cli *http.Client, host, key, user string, lim RateLimiter, window time.Duration, log *logp.Logger) ([]Group, http.Header, error) { if user == "" { return nil, nil, errors.New("no user specified") } + const endpoint = "/api/v1/users/{user}/groups" + path := strings.Replace(endpoint, "{user}", user, 1) + u := &url.URL{ Scheme: "https", Host: host, - Path: path.Join(endpoint, user, "groups"), + Path: path, } - return getDetails[Group](ctx, cli, u, key, true, OmitNone, lim, window, log) + return getDetails[Group](ctx, cli, u, endpoint, key, true, OmitNone, lim, window, log) } // GetGroupRoles returns Okta group roles using the groups API endpoint. host is the @@ -276,19 +282,20 @@ func GetUserGroupDetails(ctx context.Context, cli *http.Client, host, key, user // See GetUserDetails for details of the query and rate limit parameters. // // See https://developer.okta.com/docs/api/openapi/okta-management/management/tag/RoleAssignmentBGroup/#tag/RoleAssignmentBGroup/operation/listGroupAssignedRoles. -func GetGroupRoles(ctx context.Context, cli *http.Client, host, key, group string, lim *rate.Limiter, window time.Duration, log *logp.Logger) ([]Role, http.Header, error) { - const endpoint = "/api/v1/groups" - +func GetGroupRoles(ctx context.Context, cli *http.Client, host, key, group string, lim RateLimiter, window time.Duration, log *logp.Logger) ([]Role, http.Header, error) { if group == "" { return nil, nil, errors.New("no group specified") } + const endpoint = "/api/v1/groups/{group}/rules" + path := strings.Replace(endpoint, "{group}", group, 1) + u := &url.URL{ Scheme: "https", Host: host, - Path: path.Join(endpoint, group, "roles"), + Path: path, } - return getDetails[Role](ctx, cli, u, key, true, OmitNone, lim, window, log) + return getDetails[Role](ctx, cli, u, endpoint, key, true, OmitNone, lim, window, log) } // GetDeviceDetails returns Okta device details using the list devices API endpoint. host is the @@ -298,16 +305,24 @@ func GetGroupRoles(ctx context.Context, cli *http.Client, host, key, group strin // See GetUserDetails for details of the query and rate limit parameters. // // See https://developer.okta.com/docs/api/openapi/okta-management/management/tag/Device/#tag/Device/operation/listDevices for details. -func GetDeviceDetails(ctx context.Context, cli *http.Client, host, key, device string, query url.Values, lim *rate.Limiter, window time.Duration, log *logp.Logger) ([]Device, http.Header, error) { - const endpoint = "/api/v1/devices" +func GetDeviceDetails(ctx context.Context, cli *http.Client, host, key, device string, query url.Values, lim RateLimiter, window time.Duration, log *logp.Logger) ([]Device, http.Header, error) { + var endpoint string + var path string + if device == "" { + endpoint = "/api/v1/devices" + path = endpoint + } else { + endpoint = "/api/v1/devices/{device}" + path = strings.Replace(endpoint, "{device}", device, 1) + } u := &url.URL{ Scheme: "https", Host: host, - Path: path.Join(endpoint, device), + Path: path, RawQuery: query.Encode(), } - return getDetails[Device](ctx, cli, u, key, device == "", OmitNone, lim, window, log) + return getDetails[Device](ctx, cli, u, endpoint, key, device == "", OmitNone, lim, window, log) } // GetDeviceUsers returns Okta user details for users associated with the provided device identifier @@ -317,21 +332,22 @@ func GetDeviceDetails(ctx context.Context, cli *http.Client, host, key, device s // See GetUserDetails for details of the query and rate limit parameters. // // See https://developer.okta.com/docs/api/openapi/okta-management/management/tag/Device/#tag/Device/operation/listDeviceUsers for details. -func GetDeviceUsers(ctx context.Context, cli *http.Client, host, key, device string, query url.Values, omit Response, lim *rate.Limiter, window time.Duration, log *logp.Logger) ([]User, http.Header, error) { +func GetDeviceUsers(ctx context.Context, cli *http.Client, host, key, device string, query url.Values, omit Response, lim RateLimiter, window time.Duration, log *logp.Logger) ([]User, http.Header, error) { if device == "" { // No user associated with a null device. Not an error. return nil, nil, nil } - const endpoint = "/api/v1/devices" + const endpoint = "/api/v1/devices/{device}/users" + path := strings.Replace(endpoint, "{device}", device, 1) u := &url.URL{ Scheme: "https", Host: host, - Path: path.Join(endpoint, device, "users"), + Path: path, RawQuery: query.Encode(), } - du, h, err := getDetails[devUser](ctx, cli, u, key, true, omit, lim, window, log) + du, h, err := getDetails[devUser](ctx, cli, u, endpoint, key, true, omit, lim, window, log) if err != nil { return nil, h, err } @@ -356,7 +372,7 @@ type devUser struct { // for the specific user are returned, otherwise a list of all users is returned. // // See GetUserDetails for details of the query and rate limit parameters. -func getDetails[E entity](ctx context.Context, cli *http.Client, u *url.URL, key string, all bool, omit Response, lim *rate.Limiter, window time.Duration, log *logp.Logger) ([]E, http.Header, error) { +func getDetails[E entity](ctx context.Context, cli *http.Client, u *url.URL, endpoint string, key string, all bool, omit Response, lim RateLimiter, window time.Duration, log *logp.Logger) ([]E, http.Header, error) { url := u.String() req, err := http.NewRequestWithContext(ctx, http.MethodGet, url, nil) if err != nil { @@ -370,8 +386,7 @@ func getDetails[E entity](ctx context.Context, cli *http.Client, u *url.URL, key req.Header.Set("Content-Type", contentType) req.Header.Set("Authorization", fmt.Sprintf("SSWS %s", key)) - log.Debugw("rate limit", "limit", lim.Limit(), "burst", lim.Burst(), "url", url) - err = lim.Wait(ctx) + err = lim.Wait(ctx, endpoint, u, log) if err != nil { return nil, nil, err } @@ -380,7 +395,7 @@ func getDetails[E entity](ctx context.Context, cli *http.Client, u *url.URL, key return nil, nil, err } defer resp.Body.Close() - err = oktaRateLimit(resp.Header, window, lim, log) + err = lim.Update(endpoint, resp.Header, window, log) if err != nil { io.Copy(io.Discard, resp.Body) return nil, nil, err @@ -443,59 +458,6 @@ func (e *Error) Error() string { return fmt.Sprintf("%s: %s", summary, strings.Join(causes, ",")) } -// oktaRateLimit implements the Okta rate limit policy translation. -// -// See https://developer.okta.com/docs/reference/rl-best-practices/ for details. -func oktaRateLimit(h http.Header, window time.Duration, limiter *rate.Limiter, log *logp.Logger) error { - limit := h.Get("X-Rate-Limit-Limit") - remaining := h.Get("X-Rate-Limit-Remaining") - reset := h.Get("X-Rate-Limit-Reset") - log.Debugw("rate limit header", "X-Rate-Limit-Limit", limit, "X-Rate-Limit-Remaining", remaining, "X-Rate-Limit-Reset", reset) - if limit == "" || remaining == "" || reset == "" { - return nil - } - - lim, err := strconv.ParseFloat(limit, 64) - if err != nil { - return err - } - rem, err := strconv.ParseFloat(remaining, 64) - if err != nil { - return err - } - rst, err := strconv.ParseInt(reset, 10, 64) - if err != nil { - return err - } - resetTime := time.Unix(rst, 0) - per := time.Until(resetTime).Seconds() - - // Be conservative here; the docs don't exactly specify burst rates. - // Make sure we can make at least one new request, even if we fail - // to get a non-zero rate.Limit. We could set to zero for the case - // that limit=rate.Inf, but that detail is not important. - burst := 1 - - rateLimit := rate.Limit(rem / per) - - // Process reset if we need to wait until reset to avoid a request against a zero quota. - if rateLimit <= 0 { - waitUntil := resetTime.UTC() - // next gives us a sane next window estimate, but the - // estimate will be overwritten when we make the next - // permissible API request. - next := rate.Limit(lim / window.Seconds()) - limiter.SetLimitAt(waitUntil, next) - limiter.SetBurstAt(waitUntil, burst) - log.Debugw("rate limit adjust", "reset_time", waitUntil, "next_rate", next, "next_burst", burst) - return nil - } - limiter.SetLimit(rateLimit) - limiter.SetBurst(burst) - log.Debugw("rate limit adjust", "set_rate", rateLimit, "set_burst", burst) - return nil -} - // Next returns the next URL query for a pagination sequence. If no further // page is available, Next returns io.EOF. func Next(h http.Header) (query url.Values, err error) { diff --git a/x-pack/filebeat/input/entityanalytics/provider/okta/internal/okta/okta_test.go b/x-pack/filebeat/input/entityanalytics/provider/okta/internal/okta/okta_test.go index 9b04d3996bf9..45b1b2a4ca4c 100644 --- a/x-pack/filebeat/input/entityanalytics/provider/okta/internal/okta/okta_test.go +++ b/x-pack/filebeat/input/entityanalytics/provider/okta/internal/okta/okta_test.go @@ -44,8 +44,8 @@ func Test(t *testing.T) { t.Skip("okta tests require ${OKTA_TOKEN} to be set") } - // Make a global limiter with the capacity to proceed once. - limiter := rate.NewLimiter(1, 1) + // Make a global limiter + limiter := NewRateLimiter() // There are a variety of windows, the most conservative is one minute. // The rate limit will be adjusted on the second call to the API if @@ -263,14 +263,14 @@ var localTests = []struct { name string msg string id string - fn func(ctx context.Context, cli *http.Client, host, key, user string, query url.Values, lim *rate.Limiter, window time.Duration, log *logp.Logger) (any, http.Header, error) + fn func(ctx context.Context, cli *http.Client, host, key, user string, query url.Values, lim RateLimiter, window time.Duration, log *logp.Logger) (any, http.Header, error) mkWant func(string) (any, error) }{ { // Test case constructed from API-returned value with details anonymised. name: "users", msg: `[{"id":"userid","status":"STATUS","created":"2023-05-14T13:37:20.000Z","activated":null,"statusChanged":"2023-05-15T01:50:30.000Z","lastLogin":"2023-05-15T01:59:20.000Z","lastUpdated":"2023-05-15T01:50:32.000Z","passwordChanged":"2023-05-15T01:50:32.000Z","recovery_question":{"question":"Who's a major player in the cowboy scene?","answer":"Annie Oakley"},"type":{"id":"typeid"},"profile":{"firstName":"name","lastName":"surname","mobilePhone":null,"secondEmail":null,"login":"name.surname@example.com","email":"name.surname@example.com"},"credentials":{"password":{"value":"secret"},"emails":[{"value":"name.surname@example.com","status":"VERIFIED","type":"PRIMARY"}],"provider":{"type":"OKTA","name":"OKTA"}},"_links":{"self":{"href":"https://localhost/api/v1/users/userid"}}}]`, - fn: func(ctx context.Context, cli *http.Client, host, key, user string, query url.Values, lim *rate.Limiter, window time.Duration, log *logp.Logger) (any, http.Header, error) { + fn: func(ctx context.Context, cli *http.Client, host, key, user string, query url.Values, lim RateLimiter, window time.Duration, log *logp.Logger) (any, http.Header, error) { return GetUserDetails(context.Background(), cli, host, key, user, query, OmitNone, lim, window, log) }, mkWant: mkWant[User], @@ -279,7 +279,7 @@ var localTests = []struct { // Test case from https://developer.okta.com/docs/api/openapi/okta-management/management/tag/Device/#tag/Device/operation/listDevices name: "devices", msg: `[{"id":"devid","status":"CREATED","created":"2019-10-02T18:03:07.000Z","lastUpdated":"2019-10-02T18:03:07.000Z","profile":{"displayName":"Example Device name 1","platform":"WINDOWS","serialNumber":"XXDDRFCFRGF3M8MD6D","sid":"S-1-11-111","registered":true,"secureHardwarePresent":false,"diskEncryptionType":"ALL_INTERNAL_VOLUMES"},"resourceType":"UDDevice","resourceDisplayName":{"value":"Example Device name 1","sensitive":false},"resourceAlternateId":null,"resourceId":"guo4a5u7YAHhjXrMK0g4","_links":{"activate":{"href":"https://{yourOktaDomain}/api/v1/devices/guo4a5u7YAHhjXrMK0g4/lifecycle/activate","hints":{"allow":["POST"]}},"self":{"href":"https://{yourOktaDomain}/api/v1/devices/guo4a5u7YAHhjXrMK0g4","hints":{"allow":["GET","PATCH","PUT"]}},"users":{"href":"https://{yourOktaDomain}/api/v1/devices/guo4a5u7YAHhjXrMK0g4/users","hints":{"allow":["GET"]}}}},{"id":"guo4a5u7YAHhjXrMK0g5","status":"ACTIVE","created":"2023-06-21T23:24:02.000Z","lastUpdated":"2023-06-21T23:24:02.000Z","profile":{"displayName":"Example Device name 2","platform":"ANDROID","manufacturer":"Google","model":"Pixel 6","osVersion":"13:2023-05-05","registered":true,"secureHardwarePresent":true,"diskEncryptionType":"USER"},"resourceType":"UDDevice","resourceDisplayName":{"value":"Example Device name 2","sensitive":false},"resourceAlternateId":null,"resourceId":"guo4a5u7YAHhjXrMK0g5","_links":{"activate":{"href":"https://{yourOktaDomain}/api/v1/devices/guo4a5u7YAHhjXrMK0g5/lifecycle/activate","hints":{"allow":["POST"]}},"self":{"href":"https://{yourOktaDomain}/api/v1/devices/guo4a5u7YAHhjXrMK0g5","hints":{"allow":["GET","PATCH","PUT"]}},"users":{"href":"https://{yourOktaDomain}/api/v1/devices/guo4a5u7YAHhjXrMK0g5/users","hints":{"allow":["GET"]}}}}]`, - fn: func(ctx context.Context, cli *http.Client, host, key, device string, query url.Values, lim *rate.Limiter, window time.Duration, log *logp.Logger) (any, http.Header, error) { + fn: func(ctx context.Context, cli *http.Client, host, key, device string, query url.Values, lim RateLimiter, window time.Duration, log *logp.Logger) (any, http.Header, error) { return GetDeviceDetails(context.Background(), cli, host, key, device, query, lim, window, log) }, mkWant: mkWant[Device], @@ -289,7 +289,7 @@ var localTests = []struct { name: "devices_users", msg: `[{"created":"2023-08-07T21:48:27.000Z","managementStatus":"NOT_MANAGED","user":{"id":"userid","status":"STATUS","created":"2023-05-14T13:37:20.000Z","activated":null,"statusChanged":"2023-05-15T01:50:30.000Z","lastLogin":"2023-05-15T01:59:20.000Z","lastUpdated":"2023-05-15T01:50:32.000Z","passwordChanged":"2023-05-15T01:50:32.000Z","type":{"id":"typeid"},"profile":{"firstName":"name","lastName":"surname","mobilePhone":null,"secondEmail":null,"login":"name.surname@example.com","email":"name.surname@example.com"},"credentials":{"password":{"value":"secret"},"recovery_question":{"question":"Who's a major player in the cowboy scene?","answer":"Annie Oakley"},"emails":[{"value":"name.surname@example.com","status":"VERIFIED","type":"PRIMARY"}],"provider":{"type":"OKTA","name":"OKTA"}},"_links":{"self":{"href":"https://localhost/api/v1/users/userid"}}}}]`, id: "devid", - fn: func(ctx context.Context, cli *http.Client, host, key, device string, query url.Values, lim *rate.Limiter, window time.Duration, log *logp.Logger) (any, http.Header, error) { + fn: func(ctx context.Context, cli *http.Client, host, key, device string, query url.Values, lim RateLimiter, window time.Duration, log *logp.Logger) (any, http.Header, error) { return GetDeviceUsers(context.Background(), cli, host, key, device, query, OmitNone, lim, window, log) }, mkWant: mkWant[devUser], @@ -315,9 +315,7 @@ func TestLocal(t *testing.T) { for _, test := range localTests { t.Run(test.name, func(t *testing.T) { - // Make a global limiter with more capacity than will be set by the mock API. - // This will show the burst drop. - limiter := rate.NewLimiter(10, 10) + limiter := NewRateLimiter() // There are a variety of windows, the most conservative is one minute. // The rate limit will be adjusted on the second call to the API if @@ -377,12 +375,23 @@ func TestLocal(t *testing.T) { t.Errorf("unexpected result:\n- want\n+ got\n%s", cmp.Diff(want, got)) } - lim := limiter.Limit() - if lim < 49.0/60.0 || 50.0/60.0 < lim { - t.Errorf("unexpected rate limit (outside [49/60, 50/60]: %f", lim) + if len(limiter) != 1 { + t.Errorf("unexpected number endpoints track by rate limiter: %d", len(limiter)) } - if limiter.Burst() != 1 { // Set in GetUserDetails. - t.Errorf("unexpected burst: got:%d want:1", limiter.Burst()) + // retrieve the rate.Limiter parameters for the one endpoint + var limit rate.Limit + var burst int + for _, l := range limiter { + limit = l.Limit() + burst = l.Burst() + break + } + + if limit < 49.0/60.0 || 50.0/60.0 < limit { + t.Errorf("unexpected rate limit (outside [49/60, 50/60]: %f", limit) + } + if burst != 1 { + t.Errorf("unexpected burst: got:%d want:1", burst) } next, err := Next(h) diff --git a/x-pack/filebeat/input/entityanalytics/provider/okta/internal/okta/ratelimiter.go b/x-pack/filebeat/input/entityanalytics/provider/okta/internal/okta/ratelimiter.go new file mode 100644 index 000000000000..1b58e01328c6 --- /dev/null +++ b/x-pack/filebeat/input/entityanalytics/provider/okta/internal/okta/ratelimiter.go @@ -0,0 +1,97 @@ +// Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one +// or more contributor license agreements. Licensed under the Elastic License; +// you may not use this file except in compliance with the Elastic License. + +package okta + +import ( + "context" + "net/http" + "net/url" + "strconv" + "time" + + "golang.org/x/time/rate" + + "github.com/elastic/elastic-agent-libs/logp" +) + +type RateLimiter map[string]*rate.Limiter + +func NewRateLimiter() RateLimiter { + r := make(RateLimiter) + return r +} + +func (r RateLimiter) limiter(path string) *rate.Limiter { + if existing, ok := r[path]; ok { + return existing + } + initial := rate.NewLimiter(1, 1) // Allow a single fetch operation to obtain limits from the API + r[path] = initial + return initial +} + +func (r RateLimiter) Wait(ctx context.Context, endpoint string, url *url.URL, log *logp.Logger) (err error) { + limiter := r.limiter(endpoint) + log.Debugw("rate limit", "limit", limiter.Limit(), "burst", limiter.Burst(), "url", url.String()) + return limiter.Wait(ctx) +} + +// Update implements the Okta rate limit policy translation. +// +// See https://developer.okta.com/docs/reference/rl-best-practices/ for details. +func (r RateLimiter) Update(endpoint string, h http.Header, window time.Duration, log *logp.Logger) error { + limiter := r.limiter(endpoint) + limit := h.Get("X-Rate-Limit-Limit") + remaining := h.Get("X-Rate-Limit-Remaining") + reset := h.Get("X-Rate-Limit-Reset") + log.Debugw("rate limit header", "X-Rate-Limit-Limit", limit, "X-Rate-Limit-Remaining", remaining, "X-Rate-Limit-Reset", reset) + if limit == "" || remaining == "" || reset == "" { + return nil + } + + lim, err := strconv.ParseFloat(limit, 64) + if err != nil { + return err + } + rem, err := strconv.ParseFloat(remaining, 64) + if err != nil { + return err + } + rst, err := strconv.ParseInt(reset, 10, 64) + if err != nil { + return err + } + resetTime := time.Unix(rst, 0) + per := time.Until(resetTime).Seconds() + + // Be conservative here; the docs don't exactly specify burst rates. + // Make sure we can make at least one new request, even if we fail + // to get a non-zero rate.Limit. We could set to zero for the case + // that limit=rate.Inf, but that detail is not important. + burst := 1 + + rateLimit := rate.Limit(rem / per) + + // Process reset if we need to wait until reset to avoid a request against a zero quota. + if rateLimit <= 0 { + // Reset limiter to block requests until reset + limiter := rate.NewLimiter(0, 0) + r[endpoint] = limiter + + // next gives us a sane next window estimate, but the + // estimate will be overwritten when we make the next + // permissible API request. + next := rate.Limit(lim / window.Seconds()) + waitUntil := resetTime.UTC() + limiter.SetLimitAt(waitUntil, next) + limiter.SetBurstAt(waitUntil, burst) + log.Debugw("rate limit reset", "reset_time", waitUntil, "next_rate", next, "next_burst", burst) + return nil + } + limiter.SetLimit(rateLimit) + limiter.SetBurst(burst) + log.Debugw("rate limit adjust", "set_rate", rateLimit, "set_burst", burst) + return nil +} diff --git a/x-pack/filebeat/input/entityanalytics/provider/okta/internal/okta/ratelimiter_test.go b/x-pack/filebeat/input/entityanalytics/provider/okta/internal/okta/ratelimiter_test.go new file mode 100644 index 000000000000..1492e55c8a67 --- /dev/null +++ b/x-pack/filebeat/input/entityanalytics/provider/okta/internal/okta/ratelimiter_test.go @@ -0,0 +1,84 @@ +// Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one +// or more contributor license agreements. Licensed under the Elastic License; +// you may not use this file except in compliance with the Elastic License. + +package okta + +import ( + "net/http" + "strconv" + "testing" + "time" + + "github.com/elastic/elastic-agent-libs/logp" +) + +func TestRateLimiter(t *testing.T) { + logp.TestingSetup() + + t.Run("separation by endpoint", func(t *testing.T) { + r := NewRateLimiter() + limiter1 := r.limiter("/foo") + limiter2 := r.limiter("/bar") + + limiter1.SetBurst(1000) + + if limiter2.Burst() == 1000 { + t.Errorf("changes to one endpoint's limits affected another") + } + }) + + t.Run("Update stops requests when none are remaining", func(t *testing.T) { + r := NewRateLimiter() + + const endpoint = "/foo" + limiter := r.limiter(endpoint) + + if !limiter.Allow() { + t.Errorf("doesn't allow an initial request") + } + + now := time.Now().Unix() + reset := now + 30 + + headers := http.Header{ + "X-Rate-Limit-Limit": []string{"60"}, + "X-Rate-Limit-Remaining": []string{"0"}, + "X-Rate-Limit-Reset": []string{strconv.FormatInt(reset, 10)}, + } + window := time.Minute + + err := r.Update(endpoint, headers, window, logp.L()) + if err != nil { + t.Errorf("unexpected error from Update(): %v", err) + } + limiter = r.limiter(endpoint) + + if limiter.Allow() { + t.Errorf("allowed a request when none are remaining") + } + + if limiter.AllowN(time.Unix(reset-1, 999999999), 1) { + t.Errorf("allowed a request before reset, when none are remaining") + } + + if !limiter.AllowN(time.Unix(reset+1, 0), 1) { + t.Errorf("doesn't allow requests to resume after reset") + } + + if limiter.Limit() != 1.0 { + t.Errorf("unexpected rate following reset (not 60 requests / 60 seconds): %f", limiter.Limit()) + } + + if limiter.Burst() != 1 { + t.Errorf("unexpected burst following reset (not 1): %d", limiter.Burst()) + } + + limiter.SetBurstAt(time.Unix(reset, 0), 100) // increase bucket size to check token accumulation + tokens := limiter.TokensAt(time.Unix(reset+30, 0)) + if tokens < 29.5 || tokens > 30.0 { + t.Errorf("tokens don't accumulate at the expected rate. tokens 30s after reset: %f", tokens) + } + + }) +} diff --git a/x-pack/filebeat/input/entityanalytics/provider/okta/okta.go b/x-pack/filebeat/input/entityanalytics/provider/okta/okta.go index 5d68cf3f5c4a..30103d3ccdb7 100644 --- a/x-pack/filebeat/input/entityanalytics/provider/okta/okta.go +++ b/x-pack/filebeat/input/entityanalytics/provider/okta/okta.go @@ -23,7 +23,6 @@ import ( "go.elastic.co/ecszap" "go.uber.org/zap" "go.uber.org/zap/zapcore" - "golang.org/x/time/rate" v2 "github.com/elastic/beats/v7/filebeat/input/v2" "github.com/elastic/beats/v7/libbeat/beat" @@ -60,7 +59,7 @@ type oktaInput struct { cfg conf client *http.Client - lim *rate.Limiter + lim okta.RateLimiter metrics *inputMetrics logger *logp.Logger @@ -111,7 +110,7 @@ func (p *oktaInput) Run(inputCtx v2.Context, store *kvstore.Store, client beat.C updateTimer := time.NewTimer(updateWaitTime) // Allow a single fetch operation to obtain limits from the API. - p.lim = rate.NewLimiter(1, 1) + p.lim = okta.NewRateLimiter() if p.cfg.Tracer != nil { id := sanitizeFileName(inputCtx.IDWithoutName) diff --git a/x-pack/filebeat/input/entityanalytics/provider/okta/okta_test.go b/x-pack/filebeat/input/entityanalytics/provider/okta/okta_test.go index 5752370c4ce2..e7e2bffbba24 100644 --- a/x-pack/filebeat/input/entityanalytics/provider/okta/okta_test.go +++ b/x-pack/filebeat/input/entityanalytics/provider/okta/okta_test.go @@ -18,7 +18,6 @@ import ( "testing" "time" - "golang.org/x/time/rate" "gopkg.in/natefinch/lumberjack.v2" "github.com/elastic/beats/v7/x-pack/filebeat/input/entityanalytics/provider/okta/internal/okta" @@ -177,6 +176,7 @@ func TestOktaDoFetch(t *testing.T) { if err != nil { t.Errorf("failed to parse server URL: %v", err) } + rateLimiter := okta.NewRateLimiter() a := oktaInput{ cfg: conf{ OktaDomain: u.Host, @@ -185,7 +185,7 @@ func TestOktaDoFetch(t *testing.T) { EnrichWith: test.enrichWith, }, client: ts.Client(), - lim: rate.NewLimiter(1, 1), + lim: rateLimiter, logger: logp.L(), } if *trace { From 83251eafbc91c219ead934b5ed753d1be9a6694d Mon Sep 17 00:00:00 2001 From: Anderson Queiroz Date: Thu, 5 Dec 2024 12:15:15 +0100 Subject: [PATCH 19/48] invoke m.Run on TestMain and reduce test flakiness (#41891) Some TestMain were not running any tests as they did not invoke m.Run. This change fixes that. Also other tests were presenting some flakyness, therefore this change also attempts to fix the flakiness by setting really unique IDs for filestream tests and increasing a timeout for TestTranslateGUIDWithLDAP. --- .../autodiscover/builder/hints/logs_test.go | 5 +- .../filestream/input_integration_test.go | 169 ++++++++++-------- .../add_kubernetes_metadata/matchers_test.go | 3 + .../translate_ldap_attribute_test.go | 4 +- .../appender/kubernetes/token/token_test.go | 2 + .../builder/hints/metrics_test.go | 2 + 6 files changed, 111 insertions(+), 74 deletions(-) diff --git a/filebeat/autodiscover/builder/hints/logs_test.go b/filebeat/autodiscover/builder/hints/logs_test.go index 5e76c8d53440..402ceadfde44 100644 --- a/filebeat/autodiscover/builder/hints/logs_test.go +++ b/filebeat/autodiscover/builder/hints/logs_test.go @@ -18,6 +18,7 @@ package hints import ( + "os" "path/filepath" "testing" @@ -30,8 +31,10 @@ import ( "github.com/elastic/elastic-agent-libs/paths" ) -func TestMain(t *testing.M) { +func TestMain(m *testing.M) { InitializeModule() + + os.Exit(m.Run()) } func TestGenerateHints(t *testing.T) { diff --git a/filebeat/input/filestream/input_integration_test.go b/filebeat/input/filestream/input_integration_test.go index 79658970c3ff..80327d8bcf2c 100644 --- a/filebeat/input/filestream/input_integration_test.go +++ b/filebeat/input/filestream/input_integration_test.go @@ -30,6 +30,7 @@ import ( "testing" "time" + "github.com/gofrs/uuid/v5" "github.com/stretchr/testify/require" "golang.org/x/text/encoding" "golang.org/x/text/encoding/unicode" @@ -49,8 +50,9 @@ func TestFilestreamCloseRenamed(t *testing.T) { // than close.on_state_change.check_interval to make sure // the Harvester detects the rename first thus allowing // the output to receive the event and then close the source file. + id := "fake-ID-" + uuid.Must(uuid.NewV4()).String() inp := env.mustCreateInput(map[string]interface{}{ - "id": "fake-ID", + "id": id, "paths": []string{env.abspath(testlogName) + "*"}, "prospector.scanner.check_interval": "10ms", "close.on_state_change.check_interval": "1ms", @@ -65,7 +67,7 @@ func TestFilestreamCloseRenamed(t *testing.T) { // first event has made it successfully env.waitUntilEventCount(1) - env.requireOffsetInRegistry(testlogName, "fake-ID", len(testlines)) + env.requireOffsetInRegistry(testlogName, id, len(testlines)) testlogNameRotated := "test.log.rotated" env.mustRenameFile(testlogName, testlogNameRotated) @@ -78,8 +80,8 @@ func TestFilestreamCloseRenamed(t *testing.T) { cancelInput() env.waitUntilInputStops() - env.requireOffsetInRegistry(testlogNameRotated, "fake-ID", len(testlines)) - env.requireOffsetInRegistry(testlogName, "fake-ID", len(newerTestlines)) + env.requireOffsetInRegistry(testlogNameRotated, id, len(testlines)) + env.requireOffsetInRegistry(testlogName, id, len(newerTestlines)) } func TestFilestreamMetadataUpdatedOnRename(t *testing.T) { @@ -90,8 +92,9 @@ func TestFilestreamMetadataUpdatedOnRename(t *testing.T) { env := newInputTestingEnvironment(t) testlogName := "test.log" + id := "fake-ID-" + uuid.Must(uuid.NewV4()).String() inp := env.mustCreateInput(map[string]interface{}{ - "id": "fake-ID", + "id": id, "paths": []string{env.abspath(testlogName) + "*"}, "prospector.scanner.check_interval": "1ms", }) @@ -103,20 +106,20 @@ func TestFilestreamMetadataUpdatedOnRename(t *testing.T) { env.startInput(ctx, inp) env.waitUntilEventCount(1) - env.waitUntilMetaInRegistry(testlogName, "fake-ID", fileMeta{Source: env.abspath(testlogName), IdentifierName: "native"}) - env.requireOffsetInRegistry(testlogName, "fake-ID", len(testline)) + env.waitUntilMetaInRegistry(testlogName, id, fileMeta{Source: env.abspath(testlogName), IdentifierName: "native"}) + env.requireOffsetInRegistry(testlogName, id, len(testline)) testlogNameRenamed := "test.log.renamed" env.mustRenameFile(testlogName, testlogNameRenamed) // check if the metadata is updated and cursor data stays the same - env.waitUntilMetaInRegistry(testlogNameRenamed, "fake-ID", fileMeta{Source: env.abspath(testlogNameRenamed), IdentifierName: "native"}) - env.requireOffsetInRegistry(testlogNameRenamed, "fake-ID", len(testline)) + env.waitUntilMetaInRegistry(testlogNameRenamed, id, fileMeta{Source: env.abspath(testlogNameRenamed), IdentifierName: "native"}) + env.requireOffsetInRegistry(testlogNameRenamed, id, len(testline)) env.mustAppendToFile(testlogNameRenamed, testline) env.waitUntilEventCount(2) - env.requireOffsetInRegistry(testlogNameRenamed, "fake-ID", len(testline)*2) + env.requireOffsetInRegistry(testlogNameRenamed, id, len(testline)*2) cancelInput() env.waitUntilInputStops() @@ -127,8 +130,9 @@ func TestFilestreamCloseRemoved(t *testing.T) { env := newInputTestingEnvironment(t) testlogName := "test.log" + id := "fake-ID-" + uuid.Must(uuid.NewV4()).String() inp := env.mustCreateInput(map[string]interface{}{ - "id": "fake-ID", + "id": id, "paths": []string{env.abspath(testlogName) + "*"}, "prospector.scanner.check_interval": "24h", "close.on_state_change.check_interval": "1ms", @@ -144,7 +148,7 @@ func TestFilestreamCloseRemoved(t *testing.T) { // first event has made it successfully env.waitUntilEventCount(1) - env.requireOffsetInRegistry(testlogName, "fake-ID", len(testlines)) + env.requireOffsetInRegistry(testlogName, id, len(testlines)) fi, err := os.Stat(env.abspath(testlogName)) if err != nil { @@ -158,8 +162,8 @@ func TestFilestreamCloseRemoved(t *testing.T) { cancelInput() env.waitUntilInputStops() - id := getIDFromPath(env.abspath(testlogName), "fake-ID", fi) - env.requireOffsetInRegistryByID(id, len(testlines)) + idFromPath := getIDFromPath(env.abspath(testlogName), id, fi) + env.requireOffsetInRegistryByID(idFromPath, len(testlines)) } // test_close_eof from test_harvester.py @@ -167,8 +171,9 @@ func TestFilestreamCloseEOF(t *testing.T) { env := newInputTestingEnvironment(t) testlogName := "test.log" + id := "fake-ID-" + uuid.Must(uuid.NewV4()).String() inp := env.mustCreateInput(map[string]interface{}{ - "id": "fake-ID", + "id": id, "paths": []string{env.abspath(testlogName)}, "prospector.scanner.check_interval": "24h", "close.reader.on_eof": "true", @@ -183,7 +188,7 @@ func TestFilestreamCloseEOF(t *testing.T) { // first event has made it successfully env.waitUntilEventCount(1) - env.requireOffsetInRegistry(testlogName, "fake-ID", expectedOffset) + env.requireOffsetInRegistry(testlogName, id, expectedOffset) // the second log line will not be picked up as scan_interval is set to one day. env.mustWriteToFile(testlogName, []byte("first line\nsecond log line\n")) @@ -194,7 +199,7 @@ func TestFilestreamCloseEOF(t *testing.T) { cancelInput() env.waitUntilInputStops() - env.requireOffsetInRegistry(testlogName, "fake-ID", expectedOffset) + env.requireOffsetInRegistry(testlogName, id, expectedOffset) } // test_empty_lines from test_harvester.py @@ -202,8 +207,9 @@ func TestFilestreamEmptyLine(t *testing.T) { env := newInputTestingEnvironment(t) testlogName := "test.log" + id := "fake-ID-" + uuid.Must(uuid.NewV4()).String() inp := env.mustCreateInput(map[string]interface{}{ - "id": "fake-ID", + "id": id, "paths": []string{env.abspath(testlogName)}, "prospector.scanner.check_interval": "1ms", }) @@ -215,7 +221,7 @@ func TestFilestreamEmptyLine(t *testing.T) { env.mustWriteToFile(testlogName, testlines) env.waitUntilEventCount(2) - env.requireOffsetInRegistry(testlogName, "fake-ID", len(testlines)) + env.requireOffsetInRegistry(testlogName, id, len(testlines)) moreTestlines := []byte("\nafter an empty line\n") env.mustAppendToFile(testlogName, moreTestlines) @@ -230,7 +236,7 @@ func TestFilestreamEmptyLine(t *testing.T) { cancelInput() env.waitUntilInputStops() - env.requireOffsetInRegistry(testlogName, "fake-ID", len(testlines)+len(moreTestlines)) + env.requireOffsetInRegistry(testlogName, id, len(testlines)+len(moreTestlines)) } // test_empty_lines_only from test_harvester.py @@ -240,8 +246,9 @@ func TestFilestreamEmptyLinesOnly(t *testing.T) { env := newInputTestingEnvironment(t) testlogName := "test.log" + id := "fake-ID-" + uuid.Must(uuid.NewV4()).String() inp := env.mustCreateInput(map[string]interface{}{ - "id": "fake-ID", + "id": id, "paths": []string{env.abspath(testlogName)}, "prospector.scanner.check_interval": "1ms", }) @@ -255,7 +262,7 @@ func TestFilestreamEmptyLinesOnly(t *testing.T) { cancelInput() env.waitUntilInputStops() - env.requireNoEntryInRegistry(testlogName, "fake-ID") + env.requireNoEntryInRegistry(testlogName, id) } // test_bom_utf8 from test_harvester.py @@ -263,8 +270,9 @@ func TestFilestreamBOMUTF8(t *testing.T) { env := newInputTestingEnvironment(t) testlogName := "test.log" + id := "fake-ID-" + uuid.Must(uuid.NewV4()).String() inp := env.mustCreateInput(map[string]interface{}{ - "id": "fake-ID", + "id": id, "paths": []string{env.abspath(testlogName)}, }) @@ -305,8 +313,9 @@ func TestFilestreamUTF16BOMs(t *testing.T) { env := newInputTestingEnvironment(t) testlogName := "test.log" + id := "fake-ID-" + uuid.Must(uuid.NewV4()).String() inp := env.mustCreateInput(map[string]interface{}{ - "id": "fake-ID", + "id": id, "paths": []string{env.abspath(testlogName)}, "encoding": name, }) @@ -337,8 +346,9 @@ func TestFilestreamCloseTimeout(t *testing.T) { env := newInputTestingEnvironment(t) testlogName := "test.log" + id := "fake-ID-" + uuid.Must(uuid.NewV4()).String() inp := env.mustCreateInput(map[string]interface{}{ - "id": "fake-ID", + "id": id, "paths": []string{env.abspath(testlogName)}, "prospector.scanner.check_interval": "24h", "close.on_state_change.check_interval": "100ms", @@ -352,7 +362,7 @@ func TestFilestreamCloseTimeout(t *testing.T) { env.startInput(ctx, inp) env.waitUntilEventCount(1) - env.requireOffsetInRegistry(testlogName, "fake-ID", len(testlines)) + env.requireOffsetInRegistry(testlogName, id, len(testlines)) env.waitUntilHarvesterIsDone() env.mustWriteToFile(testlogName, []byte("first line\nsecond log line\n")) @@ -362,7 +372,7 @@ func TestFilestreamCloseTimeout(t *testing.T) { cancelInput() env.waitUntilInputStops() - env.requireOffsetInRegistry(testlogName, "fake-ID", len(testlines)) + env.requireOffsetInRegistry(testlogName, id, len(testlines)) } // test_close_inactive from test_input.py @@ -370,8 +380,9 @@ func TestFilestreamCloseAfterInterval(t *testing.T) { env := newInputTestingEnvironment(t) testlogName := "test.log" + id := "fake-ID-" + uuid.Must(uuid.NewV4()).String() inp := env.mustCreateInput(map[string]interface{}{ - "id": "fake-ID", + "id": id, "paths": []string{env.abspath(testlogName)}, "prospector.scanner.check_interval": "24h", "close.on_state_change.check_interval": "100ms", @@ -385,7 +396,7 @@ func TestFilestreamCloseAfterInterval(t *testing.T) { env.startInput(ctx, inp) env.waitUntilEventCount(3) - env.requireOffsetInRegistry(testlogName, "fake-ID", len(testlines)) + env.requireOffsetInRegistry(testlogName, id, len(testlines)) env.waitUntilHarvesterIsDone() cancelInput() @@ -397,8 +408,9 @@ func TestFilestreamCloseAfterIntervalRemoved(t *testing.T) { env := newInputTestingEnvironment(t) testlogName := "test.log" + id := "fake-ID-" + uuid.Must(uuid.NewV4()).String() inp := env.mustCreateInput(map[string]interface{}{ - "id": "fake-ID", + "id": id, "paths": []string{env.abspath(testlogName)}, "prospector.scanner.check_interval": "24h", "close.on_state_change.check_interval": "10ms", @@ -415,7 +427,7 @@ func TestFilestreamCloseAfterIntervalRemoved(t *testing.T) { env.startInput(ctx, inp) env.waitUntilEventCount(3) - env.requireOffsetInRegistry(testlogName, "fake-ID", len(testlines)) + env.requireOffsetInRegistry(testlogName, id, len(testlines)) env.mustRemoveFile(testlogName) @@ -429,8 +441,9 @@ func TestFilestreamCloseAfterIntervalRenamed(t *testing.T) { env := newInputTestingEnvironment(t) testlogName := "test.log" + id := "fake-ID-" + uuid.Must(uuid.NewV4()).String() inp := env.mustCreateInput(map[string]interface{}{ - "id": "fake-ID", + "id": id, "paths": []string{env.abspath(testlogName)}, "prospector.scanner.check_interval": "24h", "close.on_state_change.check_interval": "10ms", @@ -447,7 +460,7 @@ func TestFilestreamCloseAfterIntervalRenamed(t *testing.T) { env.startInput(ctx, inp) env.waitUntilEventCount(3) - env.requireOffsetInRegistry(testlogName, "fake-ID", len(testlines)) + env.requireOffsetInRegistry(testlogName, id, len(testlines)) newFileName := "test_rotated.log" env.mustRenameFile(testlogName, newFileName) @@ -463,8 +476,9 @@ func TestFilestreamCloseAfterIntervalRotatedAndRemoved(t *testing.T) { env := newInputTestingEnvironment(t) testlogName := "test.log" + id := "fake-ID-" + uuid.Must(uuid.NewV4()).String() inp := env.mustCreateInput(map[string]interface{}{ - "id": "fake-ID", + "id": id, "paths": []string{env.abspath(testlogName)}, "prospector.scanner.check_interval": "24h", "close.on_state_change.check_interval": "10ms", @@ -481,7 +495,7 @@ func TestFilestreamCloseAfterIntervalRotatedAndRemoved(t *testing.T) { env.startInput(ctx, inp) env.waitUntilEventCount(3) - env.requireOffsetInRegistry(testlogName, "fake-ID", len(testlines)) + env.requireOffsetInRegistry(testlogName, id, len(testlines)) newFileName := "test_rotated.log" env.mustRenameFile(testlogName, newFileName) @@ -498,8 +512,9 @@ func TestFilestreamCloseAfterIntervalRotatedAndNewRemoved(t *testing.T) { env := newInputTestingEnvironment(t) testlogName := "test.log" + id := "fake-ID-" + uuid.Must(uuid.NewV4()).String() inp := env.mustCreateInput(map[string]interface{}{ - "id": "fake-ID", + "id": id, "paths": []string{env.abspath(testlogName)}, "prospector.scanner.check_interval": "1ms", "close.on_state_change.check_interval": "10ms", @@ -516,7 +531,7 @@ func TestFilestreamCloseAfterIntervalRotatedAndNewRemoved(t *testing.T) { env.startInput(ctx, inp) env.waitUntilEventCount(3) - env.requireOffsetInRegistry(testlogName, "fake-ID", len(testlines)) + env.requireOffsetInRegistry(testlogName, id, len(testlines)) newFileName := "test_rotated.log" env.mustRenameFile(testlogName, newFileName) @@ -541,8 +556,9 @@ func TestFilestreamTruncatedFileOpen(t *testing.T) { env := newInputTestingEnvironment(t) testlogName := "test.log" + id := "fake-ID-" + uuid.Must(uuid.NewV4()).String() inp := env.mustCreateInput(map[string]interface{}{ - "id": "fake-ID", + "id": id, "paths": []string{env.abspath(testlogName)}, "prospector.scanner.check_interval": "1ms", "prospector.scanner.resend_on_touch": "true", @@ -555,7 +571,7 @@ func TestFilestreamTruncatedFileOpen(t *testing.T) { env.mustWriteToFile(testlogName, testlines) env.waitUntilEventCount(3) - env.requireOffsetInRegistry(testlogName, "fake-ID", len(testlines)) + env.requireOffsetInRegistry(testlogName, id, len(testlines)) env.mustTruncateFile(testlogName, 0) time.Sleep(5 * time.Millisecond) @@ -566,7 +582,7 @@ func TestFilestreamTruncatedFileOpen(t *testing.T) { cancelInput() env.waitUntilInputStops() - env.requireOffsetInRegistry(testlogName, "fake-ID", len(truncatedTestLines)) + env.requireOffsetInRegistry(testlogName, id, len(truncatedTestLines)) } // test_truncated_file_closed from test_harvester.py @@ -574,8 +590,9 @@ func TestFilestreamTruncatedFileClosed(t *testing.T) { env := newInputTestingEnvironment(t) testlogName := "test.log" + id := "fake-ID-" + uuid.Must(uuid.NewV4()).String() inp := env.mustCreateInput(map[string]interface{}{ - "id": "fake-ID", + "id": id, "paths": []string{env.abspath(testlogName)}, "prospector.scanner.check_interval": "1ms", "prospector.scanner.resend_on_touch": "true", @@ -589,7 +606,7 @@ func TestFilestreamTruncatedFileClosed(t *testing.T) { env.mustWriteToFile(testlogName, testlines) env.waitUntilEventCount(3) - env.requireOffsetInRegistry(testlogName, "fake-ID", len(testlines)) + env.requireOffsetInRegistry(testlogName, id, len(testlines)) env.waitUntilHarvesterIsDone() @@ -602,7 +619,7 @@ func TestFilestreamTruncatedFileClosed(t *testing.T) { cancelInput() env.waitUntilInputStops() - env.requireOffsetInRegistry(testlogName, "fake-ID", len(truncatedTestLines)) + env.requireOffsetInRegistry(testlogName, id, len(truncatedTestLines)) } // test_truncate from test_harvester.py @@ -611,8 +628,9 @@ func TestFilestreamTruncateWithSymlink(t *testing.T) { testlogName := "test.log" symlinkName := "test.log.symlink" + id := "fake-ID-" + uuid.Must(uuid.NewV4()).String() inp := env.mustCreateInput(map[string]interface{}{ - "id": "fake-ID", + "id": id, "paths": []string{ env.abspath(testlogName), env.abspath(symlinkName), @@ -632,18 +650,18 @@ func TestFilestreamTruncateWithSymlink(t *testing.T) { env.waitUntilEventCount(3) - env.requireOffsetInRegistry(testlogName, "fake-ID", len(lines)) + env.requireOffsetInRegistry(testlogName, id, len(lines)) // remove symlink env.mustRemoveFile(symlinkName) env.mustTruncateFile(testlogName, 0) - env.waitUntilOffsetInRegistry(testlogName, "fake-ID", 0, 10*time.Second) + env.waitUntilOffsetInRegistry(testlogName, id, 0, 10*time.Second) moreLines := []byte("forth line\nfifth line\n") env.mustWriteToFile(testlogName, moreLines) env.waitUntilEventCount(5) - env.requireOffsetInRegistry(testlogName, "fake-ID", len(moreLines)) + env.requireOffsetInRegistry(testlogName, id, len(moreLines)) cancelInput() env.waitUntilInputStops() @@ -655,8 +673,9 @@ func TestFilestreamTruncateBigScannerInterval(t *testing.T) { env := newInputTestingEnvironment(t) testlogName := "test.log" + id := "fake-ID-" + uuid.Must(uuid.NewV4()).String() inp := env.mustCreateInput(map[string]interface{}{ - "id": "fake-ID", + "id": id, "paths": []string{env.abspath(testlogName)}, "prospector.scanner.check_interval": "5s", "prospector.scanner.resend_on_touch": "true", @@ -669,7 +688,7 @@ func TestFilestreamTruncateBigScannerInterval(t *testing.T) { env.mustWriteToFile(testlogName, testlines) env.waitUntilEventCount(3) - env.requireOffsetInRegistry(testlogName, "fake-ID", len(testlines)) + env.requireOffsetInRegistry(testlogName, id, len(testlines)) env.mustTruncateFile(testlogName, 0) @@ -686,8 +705,9 @@ func TestFilestreamTruncateCheckOffset(t *testing.T) { env := newInputTestingEnvironment(t) testlogName := "test.log" + id := "fake-ID-" + uuid.Must(uuid.NewV4()).String() inp := env.mustCreateInput(map[string]interface{}{ - "id": "fake-ID", + "id": id, "paths": []string{env.abspath(testlogName)}, "prospector.scanner.check_interval": "1ms", "prospector.scanner.resend_on_touch": "true", @@ -700,11 +720,11 @@ func TestFilestreamTruncateCheckOffset(t *testing.T) { env.mustWriteToFile(testlogName, testlines) env.waitUntilEventCount(3) - env.requireOffsetInRegistry(testlogName, "fake-ID", len(testlines)) + env.requireOffsetInRegistry(testlogName, id, len(testlines)) env.mustTruncateFile(testlogName, 0) - env.waitUntilOffsetInRegistry(testlogName, "fake-ID", 0, 10*time.Second) + env.waitUntilOffsetInRegistry(testlogName, id, 0, 10*time.Second) cancelInput() env.waitUntilInputStops() @@ -715,8 +735,9 @@ func TestFilestreamTruncateBlockedOutput(t *testing.T) { env.pipeline = &mockPipelineConnector{blocking: true} testlogName := "test.log" + id := "fake-ID-" + uuid.Must(uuid.NewV4()).String() inp := env.mustCreateInput(map[string]interface{}{ - "id": "fake-ID", + "id": id, "paths": []string{env.abspath(testlogName)}, "prospector.scanner.check_interval": "200ms", }) @@ -734,7 +755,7 @@ func TestFilestreamTruncateBlockedOutput(t *testing.T) { env.pipeline.clients[0].canceler() env.waitUntilEventCount(2) - env.requireOffsetInRegistry(testlogName, "fake-ID", len(testlines)) + env.requireOffsetInRegistry(testlogName, id, len(testlines)) // extra lines are appended after first line is processed // so it can interfere with the truncation of the file @@ -742,7 +763,7 @@ func TestFilestreamTruncateBlockedOutput(t *testing.T) { env.mustTruncateFile(testlogName, 0) - env.waitUntilOffsetInRegistry(testlogName, "fake-ID", 0, 10*time.Second) + env.waitUntilOffsetInRegistry(testlogName, id, 0, 10*time.Second) // all newly started client has to be cancelled so events can be processed env.pipeline.cancelAllClients() @@ -753,7 +774,7 @@ func TestFilestreamTruncateBlockedOutput(t *testing.T) { env.mustWriteToFile(testlogName, truncatedTestLines) env.waitUntilEventCount(3) - env.waitUntilOffsetInRegistry(testlogName, "fake-ID", len(truncatedTestLines), 10*time.Second) + env.waitUntilOffsetInRegistry(testlogName, id, len(truncatedTestLines), 10*time.Second) cancelInput() env.waitUntilInputStops() @@ -765,8 +786,9 @@ func TestFilestreamSymlinksEnabled(t *testing.T) { testlogName := "test.log" symlinkName := "test.log.symlink" + id := "fake-ID-" + uuid.Must(uuid.NewV4()).String() inp := env.mustCreateInput(map[string]interface{}{ - "id": "fake-ID", + "id": id, "paths": []string{ env.abspath(symlinkName), }, @@ -786,7 +808,7 @@ func TestFilestreamSymlinksEnabled(t *testing.T) { cancelInput() env.waitUntilInputStops() - env.requireOffsetInRegistry(testlogName, "fake-ID", len(testlines)) + env.requireOffsetInRegistry(testlogName, id, len(testlines)) } // test_symlink_rotated from test_harvester.py @@ -796,8 +818,9 @@ func TestFilestreamSymlinkRotated(t *testing.T) { firstTestlogName := "test1.log" secondTestlogName := "test2.log" symlinkName := "test.log" + id := "fake-ID-" + uuid.Must(uuid.NewV4()).String() inp := env.mustCreateInput(map[string]interface{}{ - "id": "fake-ID", + "id": id, "paths": []string{ env.abspath(symlinkName), }, @@ -820,7 +843,7 @@ func TestFilestreamSymlinkRotated(t *testing.T) { env.waitUntilEventCount(1) expectedOffset := len(commonLine) + 2 - env.requireOffsetInRegistry(firstTestlogName, "fake-ID", expectedOffset) + env.requireOffsetInRegistry(firstTestlogName, id, expectedOffset) // rotate symlink env.mustRemoveFile(symlinkName) @@ -830,8 +853,8 @@ func TestFilestreamSymlinkRotated(t *testing.T) { env.mustAppendToFile(secondTestlogName, []byte(moreLines)) env.waitUntilEventCount(4) - env.requireOffsetInRegistry(firstTestlogName, "fake-ID", expectedOffset) - env.requireOffsetInRegistry(secondTestlogName, "fake-ID", expectedOffset+len(moreLines)) + env.requireOffsetInRegistry(firstTestlogName, id, expectedOffset) + env.requireOffsetInRegistry(secondTestlogName, id, expectedOffset+len(moreLines)) cancelInput() env.waitUntilInputStops() @@ -845,8 +868,9 @@ func TestFilestreamSymlinkRemoved(t *testing.T) { testlogName := "test.log" symlinkName := "test.log.symlink" + id := "fake-ID-" + uuid.Must(uuid.NewV4()).String() inp := env.mustCreateInput(map[string]interface{}{ - "id": "fake-ID", + "id": id, "paths": []string{ env.abspath(symlinkName), }, @@ -866,7 +890,7 @@ func TestFilestreamSymlinkRemoved(t *testing.T) { env.waitUntilEventCount(1) - env.requireOffsetInRegistry(testlogName, "fake-ID", len(line)) + env.requireOffsetInRegistry(testlogName, id, len(line)) // remove symlink env.mustRemoveFile(symlinkName) @@ -874,7 +898,7 @@ func TestFilestreamSymlinkRemoved(t *testing.T) { env.mustAppendToFile(testlogName, line) env.waitUntilEventCount(2) - env.requireOffsetInRegistry(testlogName, "fake-ID", 2*len(line)) + env.requireOffsetInRegistry(testlogName, id, 2*len(line)) cancelInput() env.waitUntilInputStops() @@ -888,8 +912,9 @@ func TestFilestreamTruncate(t *testing.T) { testlogName := "test.log" symlinkName := "test.log.symlink" + id := "fake-ID-" + uuid.Must(uuid.NewV4()).String() inp := env.mustCreateInput(map[string]interface{}{ - "id": "fake-ID", + "id": id, "paths": []string{ env.abspath("*"), }, @@ -908,12 +933,12 @@ func TestFilestreamTruncate(t *testing.T) { env.waitUntilEventCount(3) - env.requireOffsetInRegistry(testlogName, "fake-ID", len(lines)) + env.requireOffsetInRegistry(testlogName, id, len(lines)) // remove symlink env.mustRemoveFile(symlinkName) env.mustTruncateFile(testlogName, 0) - env.waitUntilOffsetInRegistry(testlogName, "fake-ID", 0, 10*time.Second) + env.waitUntilOffsetInRegistry(testlogName, id, 0, 10*time.Second) // recreate symlink env.mustSymlink(testlogName, symlinkName) @@ -921,7 +946,7 @@ func TestFilestreamTruncate(t *testing.T) { moreLines := []byte("forth line\nfifth line\n") env.mustWriteToFile(testlogName, moreLines) - env.waitUntilOffsetInRegistry(testlogName, "fake-ID", len(moreLines), 10*time.Second) + env.waitUntilOffsetInRegistry(testlogName, id, len(moreLines), 10*time.Second) cancelInput() env.waitUntilInputStops() @@ -982,8 +1007,9 @@ func TestRotatingCloseInactiveLargerWriteRate(t *testing.T) { env := newInputTestingEnvironment(t) testlogName := "test.log" + id := "fake-ID-" + uuid.Must(uuid.NewV4()).String() inp := env.mustCreateInput(map[string]interface{}{ - "id": "my-id", + "id": id, "paths": []string{ env.abspath("*"), }, @@ -1028,8 +1054,9 @@ func TestRotatingCloseInactiveLowWriteRate(t *testing.T) { env := newInputTestingEnvironment(t) testlogName := "test.log" + id := "fake-ID-" + uuid.Must(uuid.NewV4()).String() inp := env.mustCreateInput(map[string]interface{}{ - "id": "my-id", + "id": id, "paths": []string{ env.abspath("*"), }, diff --git a/filebeat/processor/add_kubernetes_metadata/matchers_test.go b/filebeat/processor/add_kubernetes_metadata/matchers_test.go index 1b2191278673..ccae66f8002f 100644 --- a/filebeat/processor/add_kubernetes_metadata/matchers_test.go +++ b/filebeat/processor/add_kubernetes_metadata/matchers_test.go @@ -19,6 +19,7 @@ package add_kubernetes_metadata import ( "fmt" + "os" "runtime" "testing" @@ -36,6 +37,8 @@ const puid = "005f3b90-4b9d-12f8-acf0-31020a840133" func TestMain(m *testing.M) { InitializeModule() + + os.Exit(m.Run()) } func TestLogsPathMatcher_InvalidSource1(t *testing.T) { diff --git a/filebeat/tests/integration/translate_ldap_attribute_test.go b/filebeat/tests/integration/translate_ldap_attribute_test.go index e2b0f877efc3..376be5e36a23 100644 --- a/filebeat/tests/integration/translate_ldap_attribute_test.go +++ b/filebeat/tests/integration/translate_ldap_attribute_test.go @@ -64,7 +64,7 @@ logging: processors: - add_fields: - fields: + fields: guid: '%s' - translate_ldap_attribute: field: fields.guid @@ -120,7 +120,7 @@ func TestTranslateGUIDWithLDAP(t *testing.T) { filebeat.WaitFileContains( outputFile, fmt.Sprintf(`"fields":{"guid":"%s","common_name":["User1","user01"]}`, entryUUID), - 10*time.Second, + 20*time.Second, ) } diff --git a/metricbeat/autodiscover/appender/kubernetes/token/token_test.go b/metricbeat/autodiscover/appender/kubernetes/token/token_test.go index aacf10b6bd0b..1fd500667992 100644 --- a/metricbeat/autodiscover/appender/kubernetes/token/token_test.go +++ b/metricbeat/autodiscover/appender/kubernetes/token/token_test.go @@ -31,6 +31,8 @@ import ( func TestMain(m *testing.M) { InitializeModule() + + os.Exit(m.Run()) } func TestTokenAppender(t *testing.T) { diff --git a/metricbeat/autodiscover/builder/hints/metrics_test.go b/metricbeat/autodiscover/builder/hints/metrics_test.go index fb0980450bd8..4cede2536eba 100644 --- a/metricbeat/autodiscover/builder/hints/metrics_test.go +++ b/metricbeat/autodiscover/builder/hints/metrics_test.go @@ -34,6 +34,8 @@ import ( func TestMain(m *testing.M) { InitializeModule() + + os.Exit(m.Run()) } func TestGenerateHints(t *testing.T) { From b1cc7c5d755eef7856389473127a8c03625f18db Mon Sep 17 00:00:00 2001 From: Nicholas Berlin <56366649+nicholasberlin@users.noreply.github.com> Date: Fri, 6 Dec 2024 09:41:13 -0500 Subject: [PATCH 20/48] Fix log file rotation bug (#41895) Fix a bug where log files are rotated on startup when interval is configured and rotateonstartup is disabled. Closes: #41894 Relates: elastic/elastic-agent-libs#259 --- CHANGELOG.next.asciidoc | 1 + NOTICE.txt | 4 ++-- go.mod | 2 +- go.sum | 4 ++-- 4 files changed, 6 insertions(+), 5 deletions(-) diff --git a/CHANGELOG.next.asciidoc b/CHANGELOG.next.asciidoc index fc83979c1734..a846236e934b 100644 --- a/CHANGELOG.next.asciidoc +++ b/CHANGELOG.next.asciidoc @@ -117,6 +117,7 @@ https://github.com/elastic/beats/compare/v8.8.1\...main[Check the HEAD diff] - Remove unnecessary debug logs during idle connection teardown {issue}40824[40824] - Fix incorrect cloud provider identification in add_cloud_metadata processor using provider priority mechanism {pull}41636[41636] - Prevent panic if libbeat processors are loaded more than once. {issue}41475[41475] {pull}41857[51857] +- Fix a bug where log files are rotated on startup when interval is configured and rotateonstartup is disabled {issue}41894[41894] {pull}41895[41895] *Auditbeat* diff --git a/NOTICE.txt b/NOTICE.txt index 1b92ea7e195f..f24525deeb39 100644 --- a/NOTICE.txt +++ b/NOTICE.txt @@ -13344,11 +13344,11 @@ SOFTWARE -------------------------------------------------------------------------------- Dependency : github.com/elastic/elastic-agent-libs -Version: v0.17.3 +Version: v0.17.4 Licence type (autodetected): Apache-2.0 -------------------------------------------------------------------------------- -Contents of probable licence file $GOMODCACHE/github.com/elastic/elastic-agent-libs@v0.17.3/LICENSE: +Contents of probable licence file $GOMODCACHE/github.com/elastic/elastic-agent-libs@v0.17.4/LICENSE: Apache License Version 2.0, January 2004 diff --git a/go.mod b/go.mod index a65edbcf230f..f935b4a98496 100644 --- a/go.mod +++ b/go.mod @@ -183,7 +183,7 @@ require ( github.com/elastic/bayeux v1.0.5 github.com/elastic/ebpfevents v0.6.0 github.com/elastic/elastic-agent-autodiscover v0.9.0 - github.com/elastic/elastic-agent-libs v0.17.3 + github.com/elastic/elastic-agent-libs v0.17.4 github.com/elastic/elastic-agent-system-metrics v0.11.4 github.com/elastic/go-elasticsearch/v8 v8.14.0 github.com/elastic/go-quark v0.2.0 diff --git a/go.sum b/go.sum index 7187e1e6138e..5b9ddab52eb8 100644 --- a/go.sum +++ b/go.sum @@ -335,8 +335,8 @@ github.com/elastic/elastic-agent-autodiscover v0.9.0 h1:+iWIKh0u3e8I+CJa3FfWe9h0 github.com/elastic/elastic-agent-autodiscover v0.9.0/go.mod h1:5iUxLHhVdaGSWYTveSwfJEY4RqPXTG13LPiFoxcpFd4= github.com/elastic/elastic-agent-client/v7 v7.15.0 h1:nDB7v8TBoNuD6IIzC3z7Q0y+7bMgXoT2DsHfolO2CHE= github.com/elastic/elastic-agent-client/v7 v7.15.0/go.mod h1:6h+f9QdIr3GO2ODC0Y8+aEXRwzbA5W4eV4dd/67z7nI= -github.com/elastic/elastic-agent-libs v0.17.3 h1:q79P05dhQkc5REzieVkkD9oRKrnptKY4MC6Typ+d8bc= -github.com/elastic/elastic-agent-libs v0.17.3/go.mod h1:5CR02awPrBr+tfmjBBK+JI+dMmHNQjpVY24J0wjbC7M= +github.com/elastic/elastic-agent-libs v0.17.4 h1:kWK5Kn2EQjM97yHqbeXv+cFAIti4IiI9Qj8huM+lZzE= +github.com/elastic/elastic-agent-libs v0.17.4/go.mod h1:5CR02awPrBr+tfmjBBK+JI+dMmHNQjpVY24J0wjbC7M= github.com/elastic/elastic-agent-system-metrics v0.11.4 h1:Z/8CML5RKvGpi6/QUFok1K3EriBAv2kUAXnsk8hCifk= github.com/elastic/elastic-agent-system-metrics v0.11.4/go.mod h1:TTW2ysv78uHBQ68hG8TXiaX1m6f29ZHgGWb8XONYsU8= github.com/elastic/elastic-transport-go/v8 v8.6.0 h1:Y2S/FBjx1LlCv5m6pWAF2kDJAHoSjSRSJCApolgfthA= From 583d3451cde4e809a8b52d94620eac248199d74b Mon Sep 17 00:00:00 2001 From: Kavindu Dodanduwa Date: Fri, 6 Dec 2024 08:37:24 -0800 Subject: [PATCH 21/48] registry cleanup for unavailable objects (#41694) Signed-off-by: Kavindu Dodanduwa # Conflicts: # x-pack/filebeat/input/awss3/states.go # x-pack/filebeat/input/awss3/states_test.go --- CHANGELOG.next.asciidoc | 1 + x-pack/filebeat/input/awss3/s3_input.go | 24 +++++- x-pack/filebeat/input/awss3/states.go | 47 +++++++++-- x-pack/filebeat/input/awss3/states_test.go | 96 +++++++++++++++++++--- 4 files changed, 145 insertions(+), 23 deletions(-) diff --git a/CHANGELOG.next.asciidoc b/CHANGELOG.next.asciidoc index a846236e934b..17aca3758321 100644 --- a/CHANGELOG.next.asciidoc +++ b/CHANGELOG.next.asciidoc @@ -357,6 +357,7 @@ https://github.com/elastic/beats/compare/v8.8.1\...main[Check the HEAD diff] - Add evaluation state dump debugging option to CEL input. {pull}41335[41335] - Added support for retry configuration in GCS input. {issue}11580[11580] {pull}41862[41862] - Improve S3 polling mode states registry when using list prefix option. {pull}41869[41869] +- AWS S3 input registry cleanup for untracked s3 objects. {pull}41694[41694] *Auditbeat* diff --git a/x-pack/filebeat/input/awss3/s3_input.go b/x-pack/filebeat/input/awss3/s3_input.go index bc8a21495e54..88f28e39e83e 100644 --- a/x-pack/filebeat/input/awss3/s3_input.go +++ b/x-pack/filebeat/input/awss3/s3_input.go @@ -115,8 +115,19 @@ func (in *s3PollerInput) runPoll(ctx context.Context) { } // Start reading data and wait for its processing to be done - in.readerLoop(ctx, workChan) + ids, ok := in.readerLoop(ctx, workChan) workerWg.Wait() + + if !ok { + in.log.Warn("skipping state registry cleanup as object reading ended with a non-ok return") + return + } + + // Perform state cleanup operation + err := in.states.CleanUp(ids) + if err != nil { + in.log.Errorf("failed to cleanup states: %v", err.Error()) + } } func (in *s3PollerInput) workerLoop(ctx context.Context, workChan <-chan state) { @@ -183,7 +194,10 @@ func (in *s3PollerInput) workerLoop(ctx context.Context, workChan <-chan state) } } -func (in *s3PollerInput) readerLoop(ctx context.Context, workChan chan<- state) { +// readerLoop performs the S3 object listing and emit state to work listeners if object needs to be processed. +// Returns all tracked state IDs correlates to all tracked S3 objects iff listing is successful. +// These IDs are intended to be used for state clean-up. +func (in *s3PollerInput) readerLoop(ctx context.Context, workChan chan<- state) (knownStateIDSlice []string, ok bool) { defer close(workChan) bucketName := getBucketNameFromARN(in.config.getBucketARN()) @@ -202,7 +216,7 @@ func (in *s3PollerInput) readerLoop(ctx context.Context, workChan chan<- state) circuitBreaker++ if circuitBreaker >= readerLoopMaxCircuitBreaker { in.log.Warnw(fmt.Sprintf("%d consecutive error when paginating listing, breaking the circuit.", circuitBreaker), "error", err) - break + return nil, false } } // add a backoff delay and try again @@ -219,6 +233,8 @@ func (in *s3PollerInput) readerLoop(ctx context.Context, workChan chan<- state) in.metrics.s3ObjectsListedTotal.Add(uint64(totListedObjects)) for _, object := range page.Contents { state := newState(bucketName, *object.Key, *object.ETag, *object.LastModified) + knownStateIDSlice = append(knownStateIDSlice, state.ID()) + if in.states.IsProcessed(state) { in.log.Debugw("skipping state.", "state", state) continue @@ -229,6 +245,8 @@ func (in *s3PollerInput) readerLoop(ctx context.Context, workChan chan<- state) in.metrics.s3ObjectsProcessedTotal.Inc() } } + + return knownStateIDSlice, true } func (in *s3PollerInput) s3EventForState(state state) s3EventV2 { diff --git a/x-pack/filebeat/input/awss3/states.go b/x-pack/filebeat/input/awss3/states.go index 8aef3de1c99e..2bfb9f29cd8b 100644 --- a/x-pack/filebeat/input/awss3/states.go +++ b/x-pack/filebeat/input/awss3/states.go @@ -21,7 +21,7 @@ const awsS3ObjectStatePrefix = "filebeat::aws-s3::state::" type states struct { // Completed S3 object states, indexed by state ID. // statesLock must be held to access states. - states map[string]state + states map[string]*state statesLock sync.Mutex // The store used to persist state changes to the registry. @@ -70,29 +70,61 @@ func (s *states) AddState(state state) error { id := state.ID() // Update in-memory copy s.statesLock.Lock() - s.states[id] = state + s.states[id] = &state s.statesLock.Unlock() // Persist to the registry s.storeLock.Lock() defer s.storeLock.Unlock() - key := awsS3ObjectStatePrefix + id - if err := s.store.Set(key, state); err != nil { + if err := s.store.Set(getStoreKey(id), state); err != nil { return err } return nil } +// CleanUp performs state and store cleanup based on provided knownIDs. +// knownIDs must contain valid currently tracked state IDs that must be known by this state registry. +// State and underlying storage will be cleaned if ID is no longer present in knownIDs set. +func (s *states) CleanUp(knownIDs []string) error { + knownIDHashSet := map[string]struct{}{} + for _, id := range knownIDs { + knownIDHashSet[id] = struct{}{} + } + + s.storeLock.Lock() + defer s.storeLock.Unlock() + s.statesLock.Lock() + defer s.statesLock.Unlock() + + for id := range s.states { + if _, contains := knownIDHashSet[id]; !contains { + // remove from sate & store as ID is no longer seen in known ID set + delete(s.states, id) + err := s.store.Remove(getStoreKey(id)) + if err != nil { + return fmt.Errorf("error while removing the state for ID %s: %w", id, err) + } + } + } + + return nil +} + func (s *states) Close() { s.storeLock.Lock() s.store.Close() s.storeLock.Unlock() } +// getStoreKey is a helper to generate the key used by underlying persistent storage +func getStoreKey(stateID string) string { + return awsS3ObjectStatePrefix + stateID +} + // loadS3StatesFromRegistry loads a copy of the registry states. // If prefix is set, entries will match the provided prefix(including empty prefix) -func loadS3StatesFromRegistry(log *logp.Logger, store *statestore.Store, prefix string) (map[string]state, error) { - stateTable := map[string]state{} +func loadS3StatesFromRegistry(log *logp.Logger, store *statestore.Store, prefix string) (map[string]*state, error) { + stateTable := map[string]*state{} err := store.Each(func(key string, dec statestore.ValueDecoder) (bool, error) { if !strings.HasPrefix(key, awsS3ObjectStatePrefix) { return true, nil @@ -117,9 +149,8 @@ func loadS3StatesFromRegistry(log *logp.Logger, store *statestore.Store, prefix // filter based on prefix and add entry to local copy if strings.HasPrefix(st.Key, prefix) { - stateTable[st.ID()] = st + stateTable[st.ID()] = &st } - return true, nil }) if err != nil { diff --git a/x-pack/filebeat/input/awss3/states_test.go b/x-pack/filebeat/input/awss3/states_test.go index 328b57003cd1..fa604ed08d96 100644 --- a/x-pack/filebeat/input/awss3/states_test.go +++ b/x-pack/filebeat/input/awss3/states_test.go @@ -5,6 +5,7 @@ package awss3 import ( + "fmt" "testing" "time" @@ -42,7 +43,7 @@ func (s *testInputStore) CleanupInterval() time.Duration { func TestStatesAddStateAndIsProcessed(t *testing.T) { type stateTestCase struct { // An initialization callback to invoke on the (initially empty) states. - statesEdit func(states *states) + statesEdit func(states *states) error // The state to call IsProcessed on and the expected result state state @@ -62,42 +63,42 @@ func TestStatesAddStateAndIsProcessed(t *testing.T) { expectedIsProcessed: false, }, "not existing state": { - statesEdit: func(states *states) { - _ = states.AddState(testState2) + statesEdit: func(states *states) error { + return states.AddState(testState2) }, state: testState1, expectedIsProcessed: false, }, "existing state": { - statesEdit: func(states *states) { - _ = states.AddState(testState1) + statesEdit: func(states *states) error { + return states.AddState(testState1) }, state: testState1, expectedIsProcessed: true, }, "existing stored state is persisted": { - statesEdit: func(states *states) { + statesEdit: func(states *states) error { state := testState1 state.Stored = true - _ = states.AddState(state) + return states.AddState(state) }, state: testState1, shouldReload: true, expectedIsProcessed: true, }, "existing failed state is persisted": { - statesEdit: func(states *states) { + statesEdit: func(states *states) error { state := testState1 state.Failed = true - _ = states.AddState(state) + return states.AddState(state) }, state: testState1, shouldReload: true, expectedIsProcessed: true, }, "existing unprocessed state is not persisted": { - statesEdit: func(states *states) { - _ = states.AddState(testState1) + statesEdit: func(states *states) error { + return states.AddState(testState1) }, state: testState1, shouldReload: true, @@ -112,7 +113,8 @@ func TestStatesAddStateAndIsProcessed(t *testing.T) { states, err := newStates(nil, store, "") require.NoError(t, err, "states creation must succeed") if test.statesEdit != nil { - test.statesEdit(states) + err = test.statesEdit(states) + require.NoError(t, err, "states edit must succeed") } if test.shouldReload { states, err = newStates(nil, store, "") @@ -125,6 +127,76 @@ func TestStatesAddStateAndIsProcessed(t *testing.T) { } } +func TestStatesCleanUp(t *testing.T) { + bucketName := "test-bucket" + lModifiedTime := time.Unix(0, 0) + stateA := newState(bucketName, "a", "a-etag", lModifiedTime) + stateB := newState(bucketName, "b", "b-etag", lModifiedTime) + stateC := newState(bucketName, "c", "c-etag", lModifiedTime) + + tests := []struct { + name string + initStates []state + knownIDs []string + expectIDs []string + }{ + { + name: "No cleanup if not missing from known list", + initStates: []state{stateA, stateB, stateC}, + knownIDs: []string{stateA.ID(), stateB.ID(), stateC.ID()}, + expectIDs: []string{stateA.ID(), stateB.ID(), stateC.ID()}, + }, + { + name: "Clean up if missing from known list", + initStates: []state{stateA, stateB, stateC}, + knownIDs: []string{stateA.ID()}, + expectIDs: []string{stateA.ID()}, + }, + { + name: "Clean up everything", + initStates: []state{stateA, stateC}, // given A, C + knownIDs: []string{stateB.ID()}, // but known B + expectIDs: []string{}, // empty state & store + }, + { + name: "Empty known IDs are valid", + initStates: []state{stateA}, // given A + knownIDs: []string{}, // Known nothing + expectIDs: []string{}, // empty state & store + }, + } + + for _, test := range tests { + t.Run(test.name, func(t *testing.T) { + store := openTestStatestore() + statesInstance, err := newStates(nil, store, "") + require.NoError(t, err, "states creation must succeed") + + for _, s := range test.initStates { + err := statesInstance.AddState(s) + require.NoError(t, err, "state initialization must succeed") + } + + // perform cleanup + err = statesInstance.CleanUp(test.knownIDs) + require.NoError(t, err, "state cleanup must succeed") + + // validate + for _, id := range test.expectIDs { + // must be in local state + _, ok := statesInstance.states[id] + require.True(t, ok, fmt.Errorf("expected id %s in state, but got missing", id)) + + // must be in store + ok, err := statesInstance.store.Has(getStoreKey(id)) + require.NoError(t, err, "state has must succeed") + require.True(t, ok, fmt.Errorf("expected id %s in store, but got missing", id)) + } + }) + } + +} + func TestStatesPrefixHandling(t *testing.T) { logger := logp.NewLogger("state-prefix-testing") From 3b5823fb631836927b82639e6dc6892236950897 Mon Sep 17 00:00:00 2001 From: Maurizio Branca Date: Fri, 6 Dec 2024 20:22:16 +0100 Subject: [PATCH 22/48] [azure-eventhub] Make the azure-eventhub input v1 tracer opt-in (#41932) Make the `azure-eventhub` input v1 internal logs tracer opt-in. To enable internal (legacy) Event Hub SDK logs, now you need to set the following environment variable: ```sh BEATS_AZURE_EVENTHUB_INPUT_TRACING_ENABLED: true ``` Before this change, the tracer was enabled by default. A few customers reported higher than anticipated error logs in edge cases. These error logs are an essential signal to troubleshoot the root cause of several issues. However, we should give the option to completely opt out from the internal logs tracing when needed. --- CHANGELOG.next.asciidoc | 1 + x-pack/filebeat/docs/inputs/input-azure-eventhub.asciidoc | 5 ++++- x-pack/filebeat/input/azureeventhub/tracer.go | 8 +++++++- 3 files changed, 12 insertions(+), 2 deletions(-) diff --git a/CHANGELOG.next.asciidoc b/CHANGELOG.next.asciidoc index 17aca3758321..466cfa7e6232 100644 --- a/CHANGELOG.next.asciidoc +++ b/CHANGELOG.next.asciidoc @@ -358,6 +358,7 @@ https://github.com/elastic/beats/compare/v8.8.1\...main[Check the HEAD diff] - Added support for retry configuration in GCS input. {issue}11580[11580] {pull}41862[41862] - Improve S3 polling mode states registry when using list prefix option. {pull}41869[41869] - AWS S3 input registry cleanup for untracked s3 objects. {pull}41694[41694] +- The environment variable `BEATS_AZURE_EVENTHUB_INPUT_TRACING_ENABLED: true` enables internal logs tracer for the azure-eventhub input. {issue}41931[41931] {pull}41932[41932] *Auditbeat* diff --git a/x-pack/filebeat/docs/inputs/input-azure-eventhub.asciidoc b/x-pack/filebeat/docs/inputs/input-azure-eventhub.asciidoc index 81cfdc66d524..808c46b83331 100644 --- a/x-pack/filebeat/docs/inputs/input-azure-eventhub.asciidoc +++ b/x-pack/filebeat/docs/inputs/input-azure-eventhub.asciidoc @@ -13,7 +13,10 @@ Users can make use of the `azure-eventhub` input in order to read messages from The azure-eventhub input implementation is based on the the event processor host (EPH is intended to be run across multiple processes and machines while load balancing message consumers more on this here https://github.com/Azure/azure-event-hubs-go#event-processor-host, https://docs.microsoft.com/en-us/azure/event-hubs/event-hubs-event-processor-host). State such as leases on partitions and checkpoints in the event stream are shared between receivers using an Azure Storage container. For this reason, as a prerequisite to using this input, users will have to create or use an existing storage account. - +Users can enable internal logs tracing for this input by setting the environment +variable `BEATS_AZURE_EVENTHUB_INPUT_TRACING_ENABLED: true`. When enabled, +this input will log additional information to the logs. Additional information +includes partition ownership, blob lease information, and other internal state. Example configuration: diff --git a/x-pack/filebeat/input/azureeventhub/tracer.go b/x-pack/filebeat/input/azureeventhub/tracer.go index f998a548e373..8ba77af3b4d3 100644 --- a/x-pack/filebeat/input/azureeventhub/tracer.go +++ b/x-pack/filebeat/input/azureeventhub/tracer.go @@ -8,6 +8,7 @@ package azureeventhub import ( "context" + "os" "github.com/devigned/tab" @@ -15,7 +16,12 @@ import ( ) func init() { - tab.Register(new(logsOnlyTracer)) + // Register the logs tracer only if the environment variable is + // set to avoid the overhead of the tracer in environments where + // it's not needed. + if os.Getenv("BEATS_AZURE_EVENTHUB_INPUT_TRACING_ENABLED") == "true" { + tab.Register(new(logsOnlyTracer)) + } } // logsOnlyTracer manages the creation of the required From 09e540c35bcd27e5962a98fc96acd2d431d5424a Mon Sep 17 00:00:00 2001 From: kruskall <99559985+kruskall@users.noreply.github.com> Date: Fri, 6 Dec 2024 21:32:22 +0100 Subject: [PATCH 23/48] feat: migrate golang mock to uber gomock (#41844) * feat: migrate golang mock to uber gomock golang mock is no longer maintained and uber gomock is recommended as the maintained fork. * lint: regenerate notice file --- NOTICE.txt | 680 ++++++++++++------ go.mod | 2 +- go.sum | 3 +- x-pack/filebeat/input/awss3/interfaces.go | 9 +- .../input/awss3/mock_interfaces_test.go | 52 +- .../input/awss3/mock_publisher_test.go | 15 +- .../filebeat/input/awss3/s3_objects_test.go | 2 +- x-pack/filebeat/input/awss3/s3_test.go | 2 +- .../filebeat/input/awss3/sqs_s3_event_test.go | 2 +- x-pack/filebeat/input/awss3/sqs_test.go | 2 +- 10 files changed, 501 insertions(+), 268 deletions(-) diff --git a/NOTICE.txt b/NOTICE.txt index f24525deeb39..4f9b5ad5e7fd 100644 --- a/NOTICE.txt +++ b/NOTICE.txt @@ -18169,218 +18169,6 @@ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLI --------------------------------------------------------------------------------- -Dependency : github.com/golang/mock -Version: v1.6.0 -Licence type (autodetected): Apache-2.0 --------------------------------------------------------------------------------- - -Contents of probable licence file $GOMODCACHE/github.com/golang/mock@v1.6.0/LICENSE: - - - Apache License - Version 2.0, January 2004 - http://www.apache.org/licenses/ - - TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION - - 1. Definitions. - - "License" shall mean the terms and conditions for use, reproduction, - and distribution as defined by Sections 1 through 9 of this document. - - "Licensor" shall mean the copyright owner or entity authorized by - the copyright owner that is granting the License. - - "Legal Entity" shall mean the union of the acting entity and all - other entities that control, are controlled by, or are under common - control with that entity. For the purposes of this definition, - "control" means (i) the power, direct or indirect, to cause the - direction or management of such entity, whether by contract or - otherwise, or (ii) ownership of fifty percent (50%) or more of the - outstanding shares, or (iii) beneficial ownership of such entity. - - "You" (or "Your") shall mean an individual or Legal Entity - exercising permissions granted by this License. - - "Source" form shall mean the preferred form for making modifications, - including but not limited to software source code, documentation - source, and configuration files. - - "Object" form shall mean any form resulting from mechanical - transformation or translation of a Source form, including but - not limited to compiled object code, generated documentation, - and conversions to other media types. - - "Work" shall mean the work of authorship, whether in Source or - Object form, made available under the License, as indicated by a - copyright notice that is included in or attached to the work - (an example is provided in the Appendix below). - - "Derivative Works" shall mean any work, whether in Source or Object - form, that is based on (or derived from) the Work and for which the - editorial revisions, annotations, elaborations, or other modifications - represent, as a whole, an original work of authorship. For the purposes - of this License, Derivative Works shall not include works that remain - separable from, or merely link (or bind by name) to the interfaces of, - the Work and Derivative Works thereof. - - "Contribution" shall mean any work of authorship, including - the original version of the Work and any modifications or additions - to that Work or Derivative Works thereof, that is intentionally - submitted to Licensor for inclusion in the Work by the copyright owner - or by an individual or Legal Entity authorized to submit on behalf of - the copyright owner. For the purposes of this definition, "submitted" - means any form of electronic, verbal, or written communication sent - to the Licensor or its representatives, including but not limited to - communication on electronic mailing lists, source code control systems, - and issue tracking systems that are managed by, or on behalf of, the - Licensor for the purpose of discussing and improving the Work, but - excluding communication that is conspicuously marked or otherwise - designated in writing by the copyright owner as "Not a Contribution." - - "Contributor" shall mean Licensor and any individual or Legal Entity - on behalf of whom a Contribution has been received by Licensor and - subsequently incorporated within the Work. - - 2. Grant of Copyright License. Subject to the terms and conditions of - this License, each Contributor hereby grants to You a perpetual, - worldwide, non-exclusive, no-charge, royalty-free, irrevocable - copyright license to reproduce, prepare Derivative Works of, - publicly display, publicly perform, sublicense, and distribute the - Work and such Derivative Works in Source or Object form. - - 3. Grant of Patent License. Subject to the terms and conditions of - this License, each Contributor hereby grants to You a perpetual, - worldwide, non-exclusive, no-charge, royalty-free, irrevocable - (except as stated in this section) patent license to make, have made, - use, offer to sell, sell, import, and otherwise transfer the Work, - where such license applies only to those patent claims licensable - by such Contributor that are necessarily infringed by their - Contribution(s) alone or by combination of their Contribution(s) - with the Work to which such Contribution(s) was submitted. If You - institute patent litigation against any entity (including a - cross-claim or counterclaim in a lawsuit) alleging that the Work - or a Contribution incorporated within the Work constitutes direct - or contributory patent infringement, then any patent licenses - granted to You under this License for that Work shall terminate - as of the date such litigation is filed. - - 4. Redistribution. You may reproduce and distribute copies of the - Work or Derivative Works thereof in any medium, with or without - modifications, and in Source or Object form, provided that You - meet the following conditions: - - (a) You must give any other recipients of the Work or - Derivative Works a copy of this License; and - - (b) You must cause any modified files to carry prominent notices - stating that You changed the files; and - - (c) You must retain, in the Source form of any Derivative Works - that You distribute, all copyright, patent, trademark, and - attribution notices from the Source form of the Work, - excluding those notices that do not pertain to any part of - the Derivative Works; and - - (d) If the Work includes a "NOTICE" text file as part of its - distribution, then any Derivative Works that You distribute must - include a readable copy of the attribution notices contained - within such NOTICE file, excluding those notices that do not - pertain to any part of the Derivative Works, in at least one - of the following places: within a NOTICE text file distributed - as part of the Derivative Works; within the Source form or - documentation, if provided along with the Derivative Works; or, - within a display generated by the Derivative Works, if and - wherever such third-party notices normally appear. The contents - of the NOTICE file are for informational purposes only and - do not modify the License. You may add Your own attribution - notices within Derivative Works that You distribute, alongside - or as an addendum to the NOTICE text from the Work, provided - that such additional attribution notices cannot be construed - as modifying the License. - - You may add Your own copyright statement to Your modifications and - may provide additional or different license terms and conditions - for use, reproduction, or distribution of Your modifications, or - for any such Derivative Works as a whole, provided Your use, - reproduction, and distribution of the Work otherwise complies with - the conditions stated in this License. - - 5. Submission of Contributions. Unless You explicitly state otherwise, - any Contribution intentionally submitted for inclusion in the Work - by You to the Licensor shall be under the terms and conditions of - this License, without any additional terms or conditions. - Notwithstanding the above, nothing herein shall supersede or modify - the terms of any separate license agreement you may have executed - with Licensor regarding such Contributions. - - 6. Trademarks. This License does not grant permission to use the trade - names, trademarks, service marks, or product names of the Licensor, - except as required for reasonable and customary use in describing the - origin of the Work and reproducing the content of the NOTICE file. - - 7. Disclaimer of Warranty. Unless required by applicable law or - agreed to in writing, Licensor provides the Work (and each - Contributor provides its Contributions) on an "AS IS" BASIS, - WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or - implied, including, without limitation, any warranties or conditions - of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A - PARTICULAR PURPOSE. You are solely responsible for determining the - appropriateness of using or redistributing the Work and assume any - risks associated with Your exercise of permissions under this License. - - 8. Limitation of Liability. In no event and under no legal theory, - whether in tort (including negligence), contract, or otherwise, - unless required by applicable law (such as deliberate and grossly - negligent acts) or agreed to in writing, shall any Contributor be - liable to You for damages, including any direct, indirect, special, - incidental, or consequential damages of any character arising as a - result of this License or out of the use or inability to use the - Work (including but not limited to damages for loss of goodwill, - work stoppage, computer failure or malfunction, or any and all - other commercial damages or losses), even if such Contributor - has been advised of the possibility of such damages. - - 9. Accepting Warranty or Additional Liability. While redistributing - the Work or Derivative Works thereof, You may choose to offer, - and charge a fee for, acceptance of support, warranty, indemnity, - or other liability obligations and/or rights consistent with this - License. However, in accepting such obligations, You may act only - on Your own behalf and on Your sole responsibility, not on behalf - of any other Contributor, and only if You agree to indemnify, - defend, and hold each Contributor harmless for any liability - incurred by, or claims asserted against, such Contributor by reason - of your accepting any such warranty or additional liability. - - END OF TERMS AND CONDITIONS - - APPENDIX: How to apply the Apache License to your work. - - To apply the Apache License to your work, attach the following - boilerplate notice, with the fields enclosed by brackets "[]" - replaced with your own identifying information. (Don't include - the brackets!) The text should be enclosed in the appropriate - comment syntax for the file format. We also recommend that a - file or class name and description of purpose be included on the - same "printed page" as the copyright notice for easier - identification within third-party archives. - - Copyright [yyyy] [name of copyright owner] - - Licensed under the Apache License, Version 2.0 (the "License"); - you may not use this file except in compliance with the License. - You may obtain a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, - WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - See the License for the specific language governing permissions and - limitations under the License. - - -------------------------------------------------------------------------------- Dependency : github.com/golang/snappy Version: v0.0.4 @@ -25376,24 +25164,236 @@ 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 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. + + +-------------------------------------------------------------------------------- +Dependency : go.mongodb.org/mongo-driver +Version: v1.14.0 +Licence type (autodetected): Apache-2.0 +-------------------------------------------------------------------------------- + +Contents of probable licence file $GOMODCACHE/go.mongodb.org/mongo-driver@v1.14.0/LICENSE: + + Apache License + Version 2.0, January 2004 + http://www.apache.org/licenses/ + + TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION + + 1. Definitions. + + "License" shall mean the terms and conditions for use, reproduction, + and distribution as defined by Sections 1 through 9 of this document. + + "Licensor" shall mean the copyright owner or entity authorized by + the copyright owner that is granting the License. + + "Legal Entity" shall mean the union of the acting entity and all + other entities that control, are controlled by, or are under common + control with that entity. For the purposes of this definition, + "control" means (i) the power, direct or indirect, to cause the + direction or management of such entity, whether by contract or + otherwise, or (ii) ownership of fifty percent (50%) or more of the + outstanding shares, or (iii) beneficial ownership of such entity. + + "You" (or "Your") shall mean an individual or Legal Entity + exercising permissions granted by this License. + + "Source" form shall mean the preferred form for making modifications, + including but not limited to software source code, documentation + source, and configuration files. + + "Object" form shall mean any form resulting from mechanical + transformation or translation of a Source form, including but + not limited to compiled object code, generated documentation, + and conversions to other media types. + + "Work" shall mean the work of authorship, whether in Source or + Object form, made available under the License, as indicated by a + copyright notice that is included in or attached to the work + (an example is provided in the Appendix below). + + "Derivative Works" shall mean any work, whether in Source or Object + form, that is based on (or derived from) the Work and for which the + editorial revisions, annotations, elaborations, or other modifications + represent, as a whole, an original work of authorship. For the purposes + of this License, Derivative Works shall not include works that remain + separable from, or merely link (or bind by name) to the interfaces of, + the Work and Derivative Works thereof. + + "Contribution" shall mean any work of authorship, including + the original version of the Work and any modifications or additions + to that Work or Derivative Works thereof, that is intentionally + submitted to Licensor for inclusion in the Work by the copyright owner + or by an individual or Legal Entity authorized to submit on behalf of + the copyright owner. For the purposes of this definition, "submitted" + means any form of electronic, verbal, or written communication sent + to the Licensor or its representatives, including but not limited to + communication on electronic mailing lists, source code control systems, + and issue tracking systems that are managed by, or on behalf of, the + Licensor for the purpose of discussing and improving the Work, but + excluding communication that is conspicuously marked or otherwise + designated in writing by the copyright owner as "Not a Contribution." + + "Contributor" shall mean Licensor and any individual or Legal Entity + on behalf of whom a Contribution has been received by Licensor and + subsequently incorporated within the Work. + + 2. Grant of Copyright License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + copyright license to reproduce, prepare Derivative Works of, + publicly display, publicly perform, sublicense, and distribute the + Work and such Derivative Works in Source or Object form. + + 3. Grant of Patent License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + (except as stated in this section) patent license to make, have made, + use, offer to sell, sell, import, and otherwise transfer the Work, + where such license applies only to those patent claims licensable + by such Contributor that are necessarily infringed by their + Contribution(s) alone or by combination of their Contribution(s) + with the Work to which such Contribution(s) was submitted. If You + institute patent litigation against any entity (including a + cross-claim or counterclaim in a lawsuit) alleging that the Work + or a Contribution incorporated within the Work constitutes direct + or contributory patent infringement, then any patent licenses + granted to You under this License for that Work shall terminate + as of the date such litigation is filed. + + 4. Redistribution. You may reproduce and distribute copies of the + Work or Derivative Works thereof in any medium, with or without + modifications, and in Source or Object form, provided that You + meet the following conditions: + + (a) You must give any other recipients of the Work or + Derivative Works a copy of this License; and + + (b) You must cause any modified files to carry prominent notices + stating that You changed the files; and + + (c) You must retain, in the Source form of any Derivative Works + that You distribute, all copyright, patent, trademark, and + attribution notices from the Source form of the Work, + excluding those notices that do not pertain to any part of + the Derivative Works; and + + (d) If the Work includes a "NOTICE" text file as part of its + distribution, then any Derivative Works that You distribute must + include a readable copy of the attribution notices contained + within such NOTICE file, excluding those notices that do not + pertain to any part of the Derivative Works, in at least one + of the following places: within a NOTICE text file distributed + as part of the Derivative Works; within the Source form or + documentation, if provided along with the Derivative Works; or, + within a display generated by the Derivative Works, if and + wherever such third-party notices normally appear. The contents + of the NOTICE file are for informational purposes only and + do not modify the License. You may add Your own attribution + notices within Derivative Works that You distribute, alongside + or as an addendum to the NOTICE text from the Work, provided + that such additional attribution notices cannot be construed + as modifying the License. + + You may add Your own copyright statement to Your modifications and + may provide additional or different license terms and conditions + for use, reproduction, or distribution of Your modifications, or + for any such Derivative Works as a whole, provided Your use, + reproduction, and distribution of the Work otherwise complies with + the conditions stated in this License. + + 5. Submission of Contributions. Unless You explicitly state otherwise, + any Contribution intentionally submitted for inclusion in the Work + by You to the Licensor shall be under the terms and conditions of + this License, without any additional terms or conditions. + Notwithstanding the above, nothing herein shall supersede or modify + the terms of any separate license agreement you may have executed + with Licensor regarding such Contributions. + + 6. Trademarks. This License does not grant permission to use the trade + names, trademarks, service marks, or product names of the Licensor, + except as required for reasonable and customary use in describing the + origin of the Work and reproducing the content of the NOTICE file. + + 7. Disclaimer of Warranty. Unless required by applicable law or + agreed to in writing, Licensor provides the Work (and each + Contributor provides its Contributions) on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or + implied, including, without limitation, any warranties or conditions + of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A + PARTICULAR PURPOSE. You are solely responsible for determining the + appropriateness of using or redistributing the Work and assume any + risks associated with Your exercise of permissions under this License. + + 8. Limitation of Liability. In no event and under no legal theory, + whether in tort (including negligence), contract, or otherwise, + unless required by applicable law (such as deliberate and grossly + negligent acts) or agreed to in writing, shall any Contributor be + liable to You for damages, including any direct, indirect, special, + incidental, or consequential damages of any character arising as a + result of this License or out of the use or inability to use the + Work (including but not limited to damages for loss of goodwill, + work stoppage, computer failure or malfunction, or any and all + other commercial damages or losses), even if such Contributor + has been advised of the possibility of such damages. + + 9. Accepting Warranty or Additional Liability. While redistributing + the Work or Derivative Works thereof, You may choose to offer, + and charge a fee for, acceptance of support, warranty, indemnity, + or other liability obligations and/or rights consistent with this + License. However, in accepting such obligations, You may act only + on Your own behalf and on Your sole responsibility, not on behalf + of any other Contributor, and only if You agree to indemnify, + defend, and hold each Contributor harmless for any liability + incurred by, or claims asserted against, such Contributor by reason + of your accepting any such warranty or additional liability. + + END OF TERMS AND CONDITIONS + + APPENDIX: How to apply the Apache License to your work. + + To apply the Apache License to your work, attach the following + boilerplate notice, with the fields enclosed by brackets "[]" + replaced with your own identifying information. (Don't include + the brackets!) The text should be enclosed in the appropriate + comment syntax for the file format. We also recommend that a + file or class name and description of purpose be included on the + same "printed page" as the copyright notice for easier + identification within third-party archives. + + Copyright [yyyy] [name of copyright owner] + + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 -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. + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. -------------------------------------------------------------------------------- -Dependency : go.mongodb.org/mongo-driver -Version: v1.14.0 +Dependency : go.opentelemetry.io/collector/component +Version: v0.109.0 Licence type (autodetected): Apache-2.0 -------------------------------------------------------------------------------- -Contents of probable licence file $GOMODCACHE/go.mongodb.org/mongo-driver@v1.14.0/LICENSE: +Contents of probable licence file $GOMODCACHE/go.opentelemetry.io/collector/component@v0.109.0/LICENSE: + Apache License Version 2.0, January 2004 @@ -25599,12 +25599,12 @@ Contents of probable licence file $GOMODCACHE/go.mongodb.org/mongo-driver@v1.14. -------------------------------------------------------------------------------- -Dependency : go.opentelemetry.io/collector/component +Dependency : go.opentelemetry.io/collector/consumer Version: v0.109.0 Licence type (autodetected): Apache-2.0 -------------------------------------------------------------------------------- -Contents of probable licence file $GOMODCACHE/go.opentelemetry.io/collector/component@v0.109.0/LICENSE: +Contents of probable licence file $GOMODCACHE/go.opentelemetry.io/collector/consumer@v0.109.0/LICENSE: Apache License @@ -25811,12 +25811,12 @@ Contents of probable licence file $GOMODCACHE/go.opentelemetry.io/collector/comp -------------------------------------------------------------------------------- -Dependency : go.opentelemetry.io/collector/consumer -Version: v0.109.0 +Dependency : go.opentelemetry.io/collector/pdata +Version: v1.15.0 Licence type (autodetected): Apache-2.0 -------------------------------------------------------------------------------- -Contents of probable licence file $GOMODCACHE/go.opentelemetry.io/collector/consumer@v0.109.0/LICENSE: +Contents of probable licence file $GOMODCACHE/go.opentelemetry.io/collector/pdata@v1.15.0/LICENSE: Apache License @@ -26023,12 +26023,12 @@ Contents of probable licence file $GOMODCACHE/go.opentelemetry.io/collector/cons -------------------------------------------------------------------------------- -Dependency : go.opentelemetry.io/collector/pdata -Version: v1.15.0 +Dependency : go.opentelemetry.io/collector/receiver +Version: v0.109.0 Licence type (autodetected): Apache-2.0 -------------------------------------------------------------------------------- -Contents of probable licence file $GOMODCACHE/go.opentelemetry.io/collector/pdata@v1.15.0/LICENSE: +Contents of probable licence file $GOMODCACHE/go.opentelemetry.io/collector/receiver@v0.109.0/LICENSE: Apache License @@ -26235,12 +26235,12 @@ Contents of probable licence file $GOMODCACHE/go.opentelemetry.io/collector/pdat -------------------------------------------------------------------------------- -Dependency : go.opentelemetry.io/collector/receiver -Version: v0.109.0 +Dependency : go.uber.org/mock +Version: v0.5.0 Licence type (autodetected): Apache-2.0 -------------------------------------------------------------------------------- -Contents of probable licence file $GOMODCACHE/go.opentelemetry.io/collector/receiver@v0.109.0/LICENSE: +Contents of probable licence file $GOMODCACHE/go.uber.org/mock@v0.5.0/LICENSE: Apache License @@ -42520,6 +42520,218 @@ third-party archives. limitations under the License. +-------------------------------------------------------------------------------- +Dependency : github.com/golang/mock +Version: v1.6.0 +Licence type (autodetected): Apache-2.0 +-------------------------------------------------------------------------------- + +Contents of probable licence file $GOMODCACHE/github.com/golang/mock@v1.6.0/LICENSE: + + + Apache License + Version 2.0, January 2004 + http://www.apache.org/licenses/ + + TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION + + 1. Definitions. + + "License" shall mean the terms and conditions for use, reproduction, + and distribution as defined by Sections 1 through 9 of this document. + + "Licensor" shall mean the copyright owner or entity authorized by + the copyright owner that is granting the License. + + "Legal Entity" shall mean the union of the acting entity and all + other entities that control, are controlled by, or are under common + control with that entity. For the purposes of this definition, + "control" means (i) the power, direct or indirect, to cause the + direction or management of such entity, whether by contract or + otherwise, or (ii) ownership of fifty percent (50%) or more of the + outstanding shares, or (iii) beneficial ownership of such entity. + + "You" (or "Your") shall mean an individual or Legal Entity + exercising permissions granted by this License. + + "Source" form shall mean the preferred form for making modifications, + including but not limited to software source code, documentation + source, and configuration files. + + "Object" form shall mean any form resulting from mechanical + transformation or translation of a Source form, including but + not limited to compiled object code, generated documentation, + and conversions to other media types. + + "Work" shall mean the work of authorship, whether in Source or + Object form, made available under the License, as indicated by a + copyright notice that is included in or attached to the work + (an example is provided in the Appendix below). + + "Derivative Works" shall mean any work, whether in Source or Object + form, that is based on (or derived from) the Work and for which the + editorial revisions, annotations, elaborations, or other modifications + represent, as a whole, an original work of authorship. For the purposes + of this License, Derivative Works shall not include works that remain + separable from, or merely link (or bind by name) to the interfaces of, + the Work and Derivative Works thereof. + + "Contribution" shall mean any work of authorship, including + the original version of the Work and any modifications or additions + to that Work or Derivative Works thereof, that is intentionally + submitted to Licensor for inclusion in the Work by the copyright owner + or by an individual or Legal Entity authorized to submit on behalf of + the copyright owner. For the purposes of this definition, "submitted" + means any form of electronic, verbal, or written communication sent + to the Licensor or its representatives, including but not limited to + communication on electronic mailing lists, source code control systems, + and issue tracking systems that are managed by, or on behalf of, the + Licensor for the purpose of discussing and improving the Work, but + excluding communication that is conspicuously marked or otherwise + designated in writing by the copyright owner as "Not a Contribution." + + "Contributor" shall mean Licensor and any individual or Legal Entity + on behalf of whom a Contribution has been received by Licensor and + subsequently incorporated within the Work. + + 2. Grant of Copyright License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + copyright license to reproduce, prepare Derivative Works of, + publicly display, publicly perform, sublicense, and distribute the + Work and such Derivative Works in Source or Object form. + + 3. Grant of Patent License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + (except as stated in this section) patent license to make, have made, + use, offer to sell, sell, import, and otherwise transfer the Work, + where such license applies only to those patent claims licensable + by such Contributor that are necessarily infringed by their + Contribution(s) alone or by combination of their Contribution(s) + with the Work to which such Contribution(s) was submitted. If You + institute patent litigation against any entity (including a + cross-claim or counterclaim in a lawsuit) alleging that the Work + or a Contribution incorporated within the Work constitutes direct + or contributory patent infringement, then any patent licenses + granted to You under this License for that Work shall terminate + as of the date such litigation is filed. + + 4. Redistribution. You may reproduce and distribute copies of the + Work or Derivative Works thereof in any medium, with or without + modifications, and in Source or Object form, provided that You + meet the following conditions: + + (a) You must give any other recipients of the Work or + Derivative Works a copy of this License; and + + (b) You must cause any modified files to carry prominent notices + stating that You changed the files; and + + (c) You must retain, in the Source form of any Derivative Works + that You distribute, all copyright, patent, trademark, and + attribution notices from the Source form of the Work, + excluding those notices that do not pertain to any part of + the Derivative Works; and + + (d) If the Work includes a "NOTICE" text file as part of its + distribution, then any Derivative Works that You distribute must + include a readable copy of the attribution notices contained + within such NOTICE file, excluding those notices that do not + pertain to any part of the Derivative Works, in at least one + of the following places: within a NOTICE text file distributed + as part of the Derivative Works; within the Source form or + documentation, if provided along with the Derivative Works; or, + within a display generated by the Derivative Works, if and + wherever such third-party notices normally appear. The contents + of the NOTICE file are for informational purposes only and + do not modify the License. You may add Your own attribution + notices within Derivative Works that You distribute, alongside + or as an addendum to the NOTICE text from the Work, provided + that such additional attribution notices cannot be construed + as modifying the License. + + You may add Your own copyright statement to Your modifications and + may provide additional or different license terms and conditions + for use, reproduction, or distribution of Your modifications, or + for any such Derivative Works as a whole, provided Your use, + reproduction, and distribution of the Work otherwise complies with + the conditions stated in this License. + + 5. Submission of Contributions. Unless You explicitly state otherwise, + any Contribution intentionally submitted for inclusion in the Work + by You to the Licensor shall be under the terms and conditions of + this License, without any additional terms or conditions. + Notwithstanding the above, nothing herein shall supersede or modify + the terms of any separate license agreement you may have executed + with Licensor regarding such Contributions. + + 6. Trademarks. This License does not grant permission to use the trade + names, trademarks, service marks, or product names of the Licensor, + except as required for reasonable and customary use in describing the + origin of the Work and reproducing the content of the NOTICE file. + + 7. Disclaimer of Warranty. Unless required by applicable law or + agreed to in writing, Licensor provides the Work (and each + Contributor provides its Contributions) on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or + implied, including, without limitation, any warranties or conditions + of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A + PARTICULAR PURPOSE. You are solely responsible for determining the + appropriateness of using or redistributing the Work and assume any + risks associated with Your exercise of permissions under this License. + + 8. Limitation of Liability. In no event and under no legal theory, + whether in tort (including negligence), contract, or otherwise, + unless required by applicable law (such as deliberate and grossly + negligent acts) or agreed to in writing, shall any Contributor be + liable to You for damages, including any direct, indirect, special, + incidental, or consequential damages of any character arising as a + result of this License or out of the use or inability to use the + Work (including but not limited to damages for loss of goodwill, + work stoppage, computer failure or malfunction, or any and all + other commercial damages or losses), even if such Contributor + has been advised of the possibility of such damages. + + 9. Accepting Warranty or Additional Liability. While redistributing + the Work or Derivative Works thereof, You may choose to offer, + and charge a fee for, acceptance of support, warranty, indemnity, + or other liability obligations and/or rights consistent with this + License. However, in accepting such obligations, You may act only + on Your own behalf and on Your sole responsibility, not on behalf + of any other Contributor, and only if You agree to indemnify, + defend, and hold each Contributor harmless for any liability + incurred by, or claims asserted against, such Contributor by reason + of your accepting any such warranty or additional liability. + + END OF TERMS AND CONDITIONS + + APPENDIX: How to apply the Apache License to your work. + + To apply the Apache License to your work, attach the following + boilerplate notice, with the fields enclosed by brackets "[]" + replaced with your own identifying information. (Don't include + the brackets!) The text should be enclosed in the appropriate + comment syntax for the file format. We also recommend that a + file or class name and description of purpose be included on the + same "printed page" as the copyright notice for easier + identification within third-party archives. + + Copyright [yyyy] [name of copyright owner] + + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. + + -------------------------------------------------------------------------------- Dependency : github.com/golang/protobuf Version: v1.5.4 diff --git a/go.mod b/go.mod index f935b4a98496..be5cc26cb320 100644 --- a/go.mod +++ b/go.mod @@ -82,7 +82,6 @@ require ( github.com/godror/godror v0.33.2 github.com/gofrs/flock v0.8.1 github.com/gogo/protobuf v1.3.2 - github.com/golang/mock v1.6.0 github.com/golang/snappy v0.0.4 github.com/gomodule/redigo v1.8.3 github.com/google/flatbuffers v24.3.25+incompatible @@ -224,6 +223,7 @@ require ( go.opentelemetry.io/collector/consumer v0.109.0 go.opentelemetry.io/collector/pdata v1.15.0 go.opentelemetry.io/collector/receiver v0.109.0 + go.uber.org/mock v0.5.0 golang.org/x/term v0.25.0 google.golang.org/genproto/googleapis/api v0.0.0-20240725223205-93522f1f2a9f gopkg.in/natefinch/lumberjack.v2 v2.2.1 diff --git a/go.sum b/go.sum index 5b9ddab52eb8..6d5130c89518 100644 --- a/go.sum +++ b/go.sum @@ -969,6 +969,8 @@ go.uber.org/atomic v1.11.0/go.mod h1:LUxbIzbOniOlMKjJjyPfpl4v+PKK2cNJn91OQbhoJI0 go.uber.org/goleak v1.1.11/go.mod h1:cwTWslyiVhfpKIDGSZEM2HlOvcqm+tG4zioyIeLoqMQ= go.uber.org/goleak v1.3.0 h1:2K3zAYmnTNqV73imy9J1T3WC+gmCePx2hEGkimedGto= go.uber.org/goleak v1.3.0/go.mod h1:CoHD4mav9JJNrW/WLlf7HGZPjdw8EucARQHekz1X6bE= +go.uber.org/mock v0.5.0 h1:KAMbZvZPyBPWgD14IrIQ38QCyjwpvVVV6K/bHl1IwQU= +go.uber.org/mock v0.5.0/go.mod h1:ge71pBPLYDk7QIi1LupWxdAykm7KIEFchiOqd6z7qMM= go.uber.org/multierr v1.6.0/go.mod h1:cdWPpRnG4AhwMwsgIHip0KRBQjJy5kYEpYjJxpXp9iU= go.uber.org/multierr v1.11.0 h1:blXXJkSxSSfBVBlC76pxqeO+LN3aDfLQo+309xJstO0= go.uber.org/multierr v1.11.0/go.mod h1:20+QtiLqy0Nd6FdQB9TLXag12DsQkrbs3htMFfDN80Y= @@ -1146,7 +1148,6 @@ golang.org/x/tools v0.0.0-20200619180055-7c47624df98f/go.mod h1:EkVYQZoAsY45+roY golang.org/x/tools v0.0.0-20200821192610-3366bbee4705/go.mod h1:njjCfa9FT2d7l9Bc6FUM5FLjQPp3cFF28FI3qnDFljA= golang.org/x/tools v0.0.0-20210106214847-113979e3529a/go.mod h1:emZCQorbCU4vsT4fOWvOPXz4eW1wZW4PmDk9uLelYpA= golang.org/x/tools v0.1.0/go.mod h1:xkSsbof2nBLbhDlRMhhhyNLN/zl3eTqcnHD5viDpcZ0= -golang.org/x/tools v0.1.1/go.mod h1:o0xws9oXOQQZyjljx8fwUC0k7L1pTE6eaCbjGeHmOkk= golang.org/x/tools v0.1.5/go.mod h1:o0xws9oXOQQZyjljx8fwUC0k7L1pTE6eaCbjGeHmOkk= golang.org/x/tools v0.1.12/go.mod h1:hNGJHUnrk76NpqgfD5Aqm5Crs+Hm0VOH/i9J2+nxYbc= golang.org/x/tools v0.6.0/go.mod h1:Xwgl3UAJ/d3gWutnCtw505GrjyAbvKui8lOU390QaIU= diff --git a/x-pack/filebeat/input/awss3/interfaces.go b/x-pack/filebeat/input/awss3/interfaces.go index 6a3b119303be..512e95893b40 100644 --- a/x-pack/filebeat/input/awss3/interfaces.go +++ b/x-pack/filebeat/input/awss3/interfaces.go @@ -27,11 +27,10 @@ import ( ) // Run 'go generate' to create mocks that are used in tests. -//go:generate go install github.com/golang/mock/mockgen@v1.6.0 -//go:generate mockgen -source=interfaces.go -destination=mock_interfaces_test.go -package awss3 -mock_names=sqsAPI=MockSQSAPI,sqsProcessor=MockSQSProcessor,s3API=MockS3API,s3Pager=MockS3Pager,s3ObjectHandlerFactory=MockS3ObjectHandlerFactory,s3ObjectHandler=MockS3ObjectHandler -//go:generate mockgen -destination=mock_publisher_test.go -package=awss3 -mock_names=Client=MockBeatClient,Pipeline=MockBeatPipeline github.com/elastic/beats/v7/libbeat/beat Client,Pipeline -//go:generate go-licenser -license Elastic . -//go:generate goimports -w -local github.com/elastic . +//go:generate go run go.uber.org/mock/mockgen -source=interfaces.go -destination=mock_interfaces_test.go -package awss3 -mock_names=sqsAPI=MockSQSAPI,sqsProcessor=MockSQSProcessor,s3API=MockS3API,s3Pager=MockS3Pager,s3ObjectHandlerFactory=MockS3ObjectHandlerFactory,s3ObjectHandler=MockS3ObjectHandler +//go:generate go run go.uber.org/mock/mockgen -destination=mock_publisher_test.go -package=awss3 -mock_names=Client=MockBeatClient,Pipeline=MockBeatPipeline github.com/elastic/beats/v7/libbeat/beat Client,Pipeline +//go:generate go run github.com/elastic/go-licenser -license Elastic . +//go:generate go run golang.org/x/tools/cmd/goimports -w -local github.com/elastic . // ------ // SQS interfaces diff --git a/x-pack/filebeat/input/awss3/mock_interfaces_test.go b/x-pack/filebeat/input/awss3/mock_interfaces_test.go index 086ca34136fd..b611802dbad7 100644 --- a/x-pack/filebeat/input/awss3/mock_interfaces_test.go +++ b/x-pack/filebeat/input/awss3/mock_interfaces_test.go @@ -4,6 +4,11 @@ // Code generated by MockGen. DO NOT EDIT. // Source: interfaces.go +// +// Generated by this command: +// +// mockgen -source=interfaces.go -destination=mock_interfaces_test.go -package awss3 -mock_names=sqsAPI=MockSQSAPI,sqsProcessor=MockSQSProcessor,s3API=MockS3API,s3Pager=MockS3Pager,s3ObjectHandlerFactory=MockS3ObjectHandlerFactory,s3ObjectHandler=MockS3ObjectHandler +// // Package awss3 is a generated GoMock package. package awss3 @@ -15,7 +20,7 @@ import ( s3 "github.com/aws/aws-sdk-go-v2/service/s3" types "github.com/aws/aws-sdk-go-v2/service/sqs/types" - gomock "github.com/golang/mock/gomock" + gomock "go.uber.org/mock/gomock" beat "github.com/elastic/beats/v7/libbeat/beat" logp "github.com/elastic/elastic-agent-libs/logp" @@ -25,6 +30,7 @@ import ( type MockSQSAPI struct { ctrl *gomock.Controller recorder *MockSQSAPIMockRecorder + isgomock struct{} } // MockSQSAPIMockRecorder is the mock recorder for MockSQSAPI. @@ -53,7 +59,7 @@ func (m *MockSQSAPI) ChangeMessageVisibility(ctx context.Context, msg *types.Mes } // ChangeMessageVisibility indicates an expected call of ChangeMessageVisibility. -func (mr *MockSQSAPIMockRecorder) ChangeMessageVisibility(ctx, msg, timeout interface{}) *gomock.Call { +func (mr *MockSQSAPIMockRecorder) ChangeMessageVisibility(ctx, msg, timeout any) *gomock.Call { mr.mock.ctrl.T.Helper() return mr.mock.ctrl.RecordCallWithMethodType(mr.mock, "ChangeMessageVisibility", reflect.TypeOf((*MockSQSAPI)(nil).ChangeMessageVisibility), ctx, msg, timeout) } @@ -67,7 +73,7 @@ func (m *MockSQSAPI) DeleteMessage(ctx context.Context, msg *types.Message) erro } // DeleteMessage indicates an expected call of DeleteMessage. -func (mr *MockSQSAPIMockRecorder) DeleteMessage(ctx, msg interface{}) *gomock.Call { +func (mr *MockSQSAPIMockRecorder) DeleteMessage(ctx, msg any) *gomock.Call { mr.mock.ctrl.T.Helper() return mr.mock.ctrl.RecordCallWithMethodType(mr.mock, "DeleteMessage", reflect.TypeOf((*MockSQSAPI)(nil).DeleteMessage), ctx, msg) } @@ -82,7 +88,7 @@ func (m *MockSQSAPI) GetQueueAttributes(ctx context.Context, attr []types.QueueA } // GetQueueAttributes indicates an expected call of GetQueueAttributes. -func (mr *MockSQSAPIMockRecorder) GetQueueAttributes(ctx, attr interface{}) *gomock.Call { +func (mr *MockSQSAPIMockRecorder) GetQueueAttributes(ctx, attr any) *gomock.Call { mr.mock.ctrl.T.Helper() return mr.mock.ctrl.RecordCallWithMethodType(mr.mock, "GetQueueAttributes", reflect.TypeOf((*MockSQSAPI)(nil).GetQueueAttributes), ctx, attr) } @@ -97,7 +103,7 @@ func (m *MockSQSAPI) ReceiveMessage(ctx context.Context, maxMessages int) ([]typ } // ReceiveMessage indicates an expected call of ReceiveMessage. -func (mr *MockSQSAPIMockRecorder) ReceiveMessage(ctx, maxMessages interface{}) *gomock.Call { +func (mr *MockSQSAPIMockRecorder) ReceiveMessage(ctx, maxMessages any) *gomock.Call { mr.mock.ctrl.T.Helper() return mr.mock.ctrl.RecordCallWithMethodType(mr.mock, "ReceiveMessage", reflect.TypeOf((*MockSQSAPI)(nil).ReceiveMessage), ctx, maxMessages) } @@ -106,6 +112,7 @@ func (mr *MockSQSAPIMockRecorder) ReceiveMessage(ctx, maxMessages interface{}) * type MockSQSProcessor struct { ctrl *gomock.Controller recorder *MockSQSProcessorMockRecorder + isgomock struct{} } // MockSQSProcessorMockRecorder is the mock recorder for MockSQSProcessor. @@ -134,7 +141,7 @@ func (m *MockSQSProcessor) ProcessSQS(ctx context.Context, msg *types.Message, e } // ProcessSQS indicates an expected call of ProcessSQS. -func (mr *MockSQSProcessorMockRecorder) ProcessSQS(ctx, msg, eventCallback interface{}) *gomock.Call { +func (mr *MockSQSProcessorMockRecorder) ProcessSQS(ctx, msg, eventCallback any) *gomock.Call { mr.mock.ctrl.T.Helper() return mr.mock.ctrl.RecordCallWithMethodType(mr.mock, "ProcessSQS", reflect.TypeOf((*MockSQSProcessor)(nil).ProcessSQS), ctx, msg, eventCallback) } @@ -143,6 +150,7 @@ func (mr *MockSQSProcessorMockRecorder) ProcessSQS(ctx, msg, eventCallback inter type MockS3API struct { ctrl *gomock.Controller recorder *MockS3APIMockRecorder + isgomock struct{} } // MockS3APIMockRecorder is the mock recorder for MockS3API. @@ -172,7 +180,7 @@ func (m *MockS3API) CopyObject(ctx context.Context, region, from_bucket, to_buck } // CopyObject indicates an expected call of CopyObject. -func (mr *MockS3APIMockRecorder) CopyObject(ctx, region, from_bucket, to_bucket, from_key, to_key interface{}) *gomock.Call { +func (mr *MockS3APIMockRecorder) CopyObject(ctx, region, from_bucket, to_bucket, from_key, to_key any) *gomock.Call { mr.mock.ctrl.T.Helper() return mr.mock.ctrl.RecordCallWithMethodType(mr.mock, "CopyObject", reflect.TypeOf((*MockS3API)(nil).CopyObject), ctx, region, from_bucket, to_bucket, from_key, to_key) } @@ -187,7 +195,7 @@ func (m *MockS3API) DeleteObject(ctx context.Context, region, bucket, key string } // DeleteObject indicates an expected call of DeleteObject. -func (mr *MockS3APIMockRecorder) DeleteObject(ctx, region, bucket, key interface{}) *gomock.Call { +func (mr *MockS3APIMockRecorder) DeleteObject(ctx, region, bucket, key any) *gomock.Call { mr.mock.ctrl.T.Helper() return mr.mock.ctrl.RecordCallWithMethodType(mr.mock, "DeleteObject", reflect.TypeOf((*MockS3API)(nil).DeleteObject), ctx, region, bucket, key) } @@ -202,7 +210,7 @@ func (m *MockS3API) GetObject(ctx context.Context, region, bucket, key string) ( } // GetObject indicates an expected call of GetObject. -func (mr *MockS3APIMockRecorder) GetObject(ctx, region, bucket, key interface{}) *gomock.Call { +func (mr *MockS3APIMockRecorder) GetObject(ctx, region, bucket, key any) *gomock.Call { mr.mock.ctrl.T.Helper() return mr.mock.ctrl.RecordCallWithMethodType(mr.mock, "GetObject", reflect.TypeOf((*MockS3API)(nil).GetObject), ctx, region, bucket, key) } @@ -216,7 +224,7 @@ func (m *MockS3API) ListObjectsPaginator(bucket, prefix string) s3Pager { } // ListObjectsPaginator indicates an expected call of ListObjectsPaginator. -func (mr *MockS3APIMockRecorder) ListObjectsPaginator(bucket, prefix interface{}) *gomock.Call { +func (mr *MockS3APIMockRecorder) ListObjectsPaginator(bucket, prefix any) *gomock.Call { mr.mock.ctrl.T.Helper() return mr.mock.ctrl.RecordCallWithMethodType(mr.mock, "ListObjectsPaginator", reflect.TypeOf((*MockS3API)(nil).ListObjectsPaginator), bucket, prefix) } @@ -225,6 +233,7 @@ func (mr *MockS3APIMockRecorder) ListObjectsPaginator(bucket, prefix interface{} type Mocks3Getter struct { ctrl *gomock.Controller recorder *Mocks3GetterMockRecorder + isgomock struct{} } // Mocks3GetterMockRecorder is the mock recorder for Mocks3Getter. @@ -254,7 +263,7 @@ func (m *Mocks3Getter) GetObject(ctx context.Context, region, bucket, key string } // GetObject indicates an expected call of GetObject. -func (mr *Mocks3GetterMockRecorder) GetObject(ctx, region, bucket, key interface{}) *gomock.Call { +func (mr *Mocks3GetterMockRecorder) GetObject(ctx, region, bucket, key any) *gomock.Call { mr.mock.ctrl.T.Helper() return mr.mock.ctrl.RecordCallWithMethodType(mr.mock, "GetObject", reflect.TypeOf((*Mocks3Getter)(nil).GetObject), ctx, region, bucket, key) } @@ -263,6 +272,7 @@ func (mr *Mocks3GetterMockRecorder) GetObject(ctx, region, bucket, key interface type Mocks3Mover struct { ctrl *gomock.Controller recorder *Mocks3MoverMockRecorder + isgomock struct{} } // Mocks3MoverMockRecorder is the mock recorder for Mocks3Mover. @@ -292,7 +302,7 @@ func (m *Mocks3Mover) CopyObject(ctx context.Context, region, from_bucket, to_bu } // CopyObject indicates an expected call of CopyObject. -func (mr *Mocks3MoverMockRecorder) CopyObject(ctx, region, from_bucket, to_bucket, from_key, to_key interface{}) *gomock.Call { +func (mr *Mocks3MoverMockRecorder) CopyObject(ctx, region, from_bucket, to_bucket, from_key, to_key any) *gomock.Call { mr.mock.ctrl.T.Helper() return mr.mock.ctrl.RecordCallWithMethodType(mr.mock, "CopyObject", reflect.TypeOf((*Mocks3Mover)(nil).CopyObject), ctx, region, from_bucket, to_bucket, from_key, to_key) } @@ -307,7 +317,7 @@ func (m *Mocks3Mover) DeleteObject(ctx context.Context, region, bucket, key stri } // DeleteObject indicates an expected call of DeleteObject. -func (mr *Mocks3MoverMockRecorder) DeleteObject(ctx, region, bucket, key interface{}) *gomock.Call { +func (mr *Mocks3MoverMockRecorder) DeleteObject(ctx, region, bucket, key any) *gomock.Call { mr.mock.ctrl.T.Helper() return mr.mock.ctrl.RecordCallWithMethodType(mr.mock, "DeleteObject", reflect.TypeOf((*Mocks3Mover)(nil).DeleteObject), ctx, region, bucket, key) } @@ -316,6 +326,7 @@ func (mr *Mocks3MoverMockRecorder) DeleteObject(ctx, region, bucket, key interfa type Mocks3Lister struct { ctrl *gomock.Controller recorder *Mocks3ListerMockRecorder + isgomock struct{} } // Mocks3ListerMockRecorder is the mock recorder for Mocks3Lister. @@ -344,7 +355,7 @@ func (m *Mocks3Lister) ListObjectsPaginator(bucket, prefix string) s3Pager { } // ListObjectsPaginator indicates an expected call of ListObjectsPaginator. -func (mr *Mocks3ListerMockRecorder) ListObjectsPaginator(bucket, prefix interface{}) *gomock.Call { +func (mr *Mocks3ListerMockRecorder) ListObjectsPaginator(bucket, prefix any) *gomock.Call { mr.mock.ctrl.T.Helper() return mr.mock.ctrl.RecordCallWithMethodType(mr.mock, "ListObjectsPaginator", reflect.TypeOf((*Mocks3Lister)(nil).ListObjectsPaginator), bucket, prefix) } @@ -353,6 +364,7 @@ func (mr *Mocks3ListerMockRecorder) ListObjectsPaginator(bucket, prefix interfac type MockS3Pager struct { ctrl *gomock.Controller recorder *MockS3PagerMockRecorder + isgomock struct{} } // MockS3PagerMockRecorder is the mock recorder for MockS3Pager. @@ -389,7 +401,7 @@ func (mr *MockS3PagerMockRecorder) HasMorePages() *gomock.Call { // NextPage mocks base method. func (m *MockS3Pager) NextPage(ctx context.Context, optFns ...func(*s3.Options)) (*s3.ListObjectsV2Output, error) { m.ctrl.T.Helper() - varargs := []interface{}{ctx} + varargs := []any{ctx} for _, a := range optFns { varargs = append(varargs, a) } @@ -400,9 +412,9 @@ func (m *MockS3Pager) NextPage(ctx context.Context, optFns ...func(*s3.Options)) } // NextPage indicates an expected call of NextPage. -func (mr *MockS3PagerMockRecorder) NextPage(ctx interface{}, optFns ...interface{}) *gomock.Call { +func (mr *MockS3PagerMockRecorder) NextPage(ctx any, optFns ...any) *gomock.Call { mr.mock.ctrl.T.Helper() - varargs := append([]interface{}{ctx}, optFns...) + varargs := append([]any{ctx}, optFns...) return mr.mock.ctrl.RecordCallWithMethodType(mr.mock, "NextPage", reflect.TypeOf((*MockS3Pager)(nil).NextPage), varargs...) } @@ -410,6 +422,7 @@ func (mr *MockS3PagerMockRecorder) NextPage(ctx interface{}, optFns ...interface type MockS3ObjectHandlerFactory struct { ctrl *gomock.Controller recorder *MockS3ObjectHandlerFactoryMockRecorder + isgomock struct{} } // MockS3ObjectHandlerFactoryMockRecorder is the mock recorder for MockS3ObjectHandlerFactory. @@ -438,7 +451,7 @@ func (m *MockS3ObjectHandlerFactory) Create(ctx context.Context, obj s3EventV2) } // Create indicates an expected call of Create. -func (mr *MockS3ObjectHandlerFactoryMockRecorder) Create(ctx, obj interface{}) *gomock.Call { +func (mr *MockS3ObjectHandlerFactoryMockRecorder) Create(ctx, obj any) *gomock.Call { mr.mock.ctrl.T.Helper() return mr.mock.ctrl.RecordCallWithMethodType(mr.mock, "Create", reflect.TypeOf((*MockS3ObjectHandlerFactory)(nil).Create), ctx, obj) } @@ -447,6 +460,7 @@ func (mr *MockS3ObjectHandlerFactoryMockRecorder) Create(ctx, obj interface{}) * type MockS3ObjectHandler struct { ctrl *gomock.Controller recorder *MockS3ObjectHandlerMockRecorder + isgomock struct{} } // MockS3ObjectHandlerMockRecorder is the mock recorder for MockS3ObjectHandler. @@ -489,7 +503,7 @@ func (m *MockS3ObjectHandler) ProcessS3Object(log *logp.Logger, eventCallback fu } // ProcessS3Object indicates an expected call of ProcessS3Object. -func (mr *MockS3ObjectHandlerMockRecorder) ProcessS3Object(log, eventCallback interface{}) *gomock.Call { +func (mr *MockS3ObjectHandlerMockRecorder) ProcessS3Object(log, eventCallback any) *gomock.Call { mr.mock.ctrl.T.Helper() return mr.mock.ctrl.RecordCallWithMethodType(mr.mock, "ProcessS3Object", reflect.TypeOf((*MockS3ObjectHandler)(nil).ProcessS3Object), log, eventCallback) } diff --git a/x-pack/filebeat/input/awss3/mock_publisher_test.go b/x-pack/filebeat/input/awss3/mock_publisher_test.go index efbd5bcef97b..3bffc9142b3f 100644 --- a/x-pack/filebeat/input/awss3/mock_publisher_test.go +++ b/x-pack/filebeat/input/awss3/mock_publisher_test.go @@ -4,6 +4,11 @@ // Code generated by MockGen. DO NOT EDIT. // Source: github.com/elastic/beats/v7/libbeat/beat (interfaces: Client,Pipeline) +// +// Generated by this command: +// +// mockgen -destination=mock_publisher_test.go -package=awss3 -mock_names=Client=MockBeatClient,Pipeline=MockBeatPipeline github.com/elastic/beats/v7/libbeat/beat Client,Pipeline +// // Package awss3 is a generated GoMock package. package awss3 @@ -11,7 +16,7 @@ package awss3 import ( reflect "reflect" - gomock "github.com/golang/mock/gomock" + gomock "go.uber.org/mock/gomock" beat "github.com/elastic/beats/v7/libbeat/beat" ) @@ -20,6 +25,7 @@ import ( type MockBeatClient struct { ctrl *gomock.Controller recorder *MockBeatClientMockRecorder + isgomock struct{} } // MockBeatClientMockRecorder is the mock recorder for MockBeatClient. @@ -60,7 +66,7 @@ func (m *MockBeatClient) Publish(arg0 beat.Event) { } // Publish indicates an expected call of Publish. -func (mr *MockBeatClientMockRecorder) Publish(arg0 interface{}) *gomock.Call { +func (mr *MockBeatClientMockRecorder) Publish(arg0 any) *gomock.Call { mr.mock.ctrl.T.Helper() return mr.mock.ctrl.RecordCallWithMethodType(mr.mock, "Publish", reflect.TypeOf((*MockBeatClient)(nil).Publish), arg0) } @@ -72,7 +78,7 @@ func (m *MockBeatClient) PublishAll(arg0 []beat.Event) { } // PublishAll indicates an expected call of PublishAll. -func (mr *MockBeatClientMockRecorder) PublishAll(arg0 interface{}) *gomock.Call { +func (mr *MockBeatClientMockRecorder) PublishAll(arg0 any) *gomock.Call { mr.mock.ctrl.T.Helper() return mr.mock.ctrl.RecordCallWithMethodType(mr.mock, "PublishAll", reflect.TypeOf((*MockBeatClient)(nil).PublishAll), arg0) } @@ -81,6 +87,7 @@ func (mr *MockBeatClientMockRecorder) PublishAll(arg0 interface{}) *gomock.Call type MockBeatPipeline struct { ctrl *gomock.Controller recorder *MockBeatPipelineMockRecorder + isgomock struct{} } // MockBeatPipelineMockRecorder is the mock recorder for MockBeatPipeline. @@ -125,7 +132,7 @@ func (m *MockBeatPipeline) ConnectWith(arg0 beat.ClientConfig) (beat.Client, err } // ConnectWith indicates an expected call of ConnectWith. -func (mr *MockBeatPipelineMockRecorder) ConnectWith(arg0 interface{}) *gomock.Call { +func (mr *MockBeatPipelineMockRecorder) ConnectWith(arg0 any) *gomock.Call { mr.mock.ctrl.T.Helper() return mr.mock.ctrl.RecordCallWithMethodType(mr.mock, "ConnectWith", reflect.TypeOf((*MockBeatPipeline)(nil).ConnectWith), arg0) } diff --git a/x-pack/filebeat/input/awss3/s3_objects_test.go b/x-pack/filebeat/input/awss3/s3_objects_test.go index 432c5209d258..e6178c33a87f 100644 --- a/x-pack/filebeat/input/awss3/s3_objects_test.go +++ b/x-pack/filebeat/input/awss3/s3_objects_test.go @@ -17,9 +17,9 @@ import ( awssdk "github.com/aws/aws-sdk-go-v2/aws" "github.com/aws/aws-sdk-go-v2/service/s3" "github.com/aws/aws-sdk-go-v2/service/s3/types" - "github.com/golang/mock/gomock" "github.com/stretchr/testify/assert" "github.com/stretchr/testify/require" + "go.uber.org/mock/gomock" "github.com/elastic/beats/v7/libbeat/beat" conf "github.com/elastic/elastic-agent-libs/config" diff --git a/x-pack/filebeat/input/awss3/s3_test.go b/x-pack/filebeat/input/awss3/s3_test.go index a1e9e02b4263..2f79cb44a48c 100644 --- a/x-pack/filebeat/input/awss3/s3_test.go +++ b/x-pack/filebeat/input/awss3/s3_test.go @@ -12,8 +12,8 @@ import ( "github.com/aws/aws-sdk-go-v2/aws" "github.com/aws/aws-sdk-go-v2/service/s3" "github.com/aws/aws-sdk-go-v2/service/s3/types" - "github.com/golang/mock/gomock" "github.com/stretchr/testify/require" + "go.uber.org/mock/gomock" "github.com/elastic/elastic-agent-libs/logp" ) diff --git a/x-pack/filebeat/input/awss3/sqs_s3_event_test.go b/x-pack/filebeat/input/awss3/sqs_s3_event_test.go index c7962bb2f0f3..ae4400dc0f27 100644 --- a/x-pack/filebeat/input/awss3/sqs_s3_event_test.go +++ b/x-pack/filebeat/input/awss3/sqs_s3_event_test.go @@ -16,9 +16,9 @@ import ( "github.com/aws/aws-sdk-go-v2/aws" "github.com/aws/aws-sdk-go-v2/service/sqs/types" - "github.com/golang/mock/gomock" "github.com/stretchr/testify/assert" "github.com/stretchr/testify/require" + "go.uber.org/mock/gomock" "github.com/elastic/beats/v7/libbeat/beat" "github.com/elastic/elastic-agent-libs/logp" diff --git a/x-pack/filebeat/input/awss3/sqs_test.go b/x-pack/filebeat/input/awss3/sqs_test.go index 8bc25397eaeb..34575a47daff 100644 --- a/x-pack/filebeat/input/awss3/sqs_test.go +++ b/x-pack/filebeat/input/awss3/sqs_test.go @@ -15,9 +15,9 @@ import ( "github.com/aws/aws-sdk-go-v2/aws" "github.com/aws/aws-sdk-go-v2/service/sqs/types" "github.com/gofrs/uuid/v5" - "github.com/golang/mock/gomock" "github.com/stretchr/testify/assert" "github.com/stretchr/testify/require" + "go.uber.org/mock/gomock" "github.com/elastic/beats/v7/libbeat/beat" "github.com/elastic/elastic-agent-libs/logp" From db2130990da0606faae12518b1537989115323d5 Mon Sep 17 00:00:00 2001 From: Dan Kortschak Date: Mon, 9 Dec 2024 06:08:58 +1030 Subject: [PATCH 24/48] x-pack/filebeat/input/cel: add evaluation coverage collection support (#41884) This allows collecting the execution coverage data from a running input. Coverage data is logged as JSON data at debug level when this option is enabled. Currently no tooling is available for rendering the data in a more human-friendly format, but the backing infrastructure for this exists in the mito repository. --- CHANGELOG-developer.next.asciidoc | 1 + .../filebeat/docs/inputs/input-cel.asciidoc | 7 +++ x-pack/filebeat/input/cel/config.go | 12 +++++- x-pack/filebeat/input/cel/input.go | 32 ++++++++++---- x-pack/filebeat/input/cel/input_test.go | 43 +++++++++++++++++++ 5 files changed, 85 insertions(+), 10 deletions(-) diff --git a/CHANGELOG-developer.next.asciidoc b/CHANGELOG-developer.next.asciidoc index 0998beb9f7d6..15b46777965f 100644 --- a/CHANGELOG-developer.next.asciidoc +++ b/CHANGELOG-developer.next.asciidoc @@ -213,6 +213,7 @@ The list below covers the major changes between 7.0.0-rc2 and main only. - Add field redaction package. {pull}40997[40997] - Add support for marked redaction to x-pack/filebeat/input/internal/private {pull}41212[41212] - Add support for collecting Okta role and factor data for users with filebeat entityanalytics input. {pull}41044[41044] +- Add CEL input program evaluation coverage collection support. {pull}41884[41884] ==== Deprecated diff --git a/x-pack/filebeat/docs/inputs/input-cel.asciidoc b/x-pack/filebeat/docs/inputs/input-cel.asciidoc index 8e062025b248..c18a687653c6 100644 --- a/x-pack/filebeat/docs/inputs/input-cel.asciidoc +++ b/x-pack/filebeat/docs/inputs/input-cel.asciidoc @@ -815,6 +815,13 @@ dump is configured, it is recommended that data input sizes be reduced to avoid making dumps that are intractable to analysis. To delete existing failure dumps, set `failure_dump.enabled` to false without unsetting the filename option. +[[cel-record-coverage]] +[float] +==== `record_coverage` + +This specifies that CEL code evaluation coverage should be recorded and logged in debug logs. This is a +developer-only option. + [float] === Metrics diff --git a/x-pack/filebeat/input/cel/config.go b/x-pack/filebeat/input/cel/config.go index aee095b199b9..1906a309bdb9 100644 --- a/x-pack/filebeat/input/cel/config.go +++ b/x-pack/filebeat/input/cel/config.go @@ -61,6 +61,10 @@ type config struct { // FailureDump configures failure dump behaviour. FailureDump *dumpConfig `config:"failure_dump"` + + // RecordCoverage indicates whether a program should + // record and log execution coverage. + RecordCoverage bool `config:"record_coverage"` } type redact struct { @@ -86,9 +90,13 @@ func (t *dumpConfig) enabled() bool { } func (c config) Validate() error { + if c.RecordCoverage { + logp.L().Named("input.cel").Warn("execution coverage enabled: " + + "see documentation for details: https://www.elastic.co/guide/en/beats/filebeat/current/filebeat-input-cel.html#cel-record-coverage") + } if c.Redact == nil { logp.L().Named("input.cel").Warn("missing recommended 'redact' configuration: " + - "see documentation for details: https://www.elastic.co/guide/en/beats/filebeat/current/filebeat-input-cel.html#_redact") + "see documentation for details: https://www.elastic.co/guide/en/beats/filebeat/current/filebeat-input-cel.html#cel-state-redact") } if c.Interval <= 0 { return errors.New("interval must be greater than 0") @@ -106,7 +114,7 @@ func (c config) Validate() error { patterns = map[string]*regexp.Regexp{".": nil} } wantDump := c.FailureDump.enabled() && c.FailureDump.Filename != "" - _, _, err = newProgram(context.Background(), c.Program, root, nil, &http.Client{}, nil, nil, patterns, c.XSDs, logp.L().Named("input.cel"), nil, wantDump) + _, _, _, err = newProgram(context.Background(), c.Program, root, nil, &http.Client{}, nil, nil, patterns, c.XSDs, logp.L().Named("input.cel"), nil, wantDump, false) if err != nil { return fmt.Errorf("failed to check program: %w", err) } diff --git a/x-pack/filebeat/input/cel/input.go b/x-pack/filebeat/input/cel/input.go index 97ab8c9bee05..4a04836bf596 100644 --- a/x-pack/filebeat/input/cel/input.go +++ b/x-pack/filebeat/input/cel/input.go @@ -168,7 +168,8 @@ func (i input) run(env v2.Context, src *source, cursor map[string]interface{}, p } } wantDump := cfg.FailureDump.enabled() && cfg.FailureDump.Filename != "" - prg, ast, err := newProgram(ctx, cfg.Program, root, getEnv(cfg.AllowedEnvironment), client, limiter, auth, patterns, cfg.XSDs, log, trace, wantDump) + doCov := cfg.RecordCoverage && log.IsDebug() + prg, ast, cov, err := newProgram(ctx, cfg.Program, root, getEnv(cfg.AllowedEnvironment), client, limiter, auth, patterns, cfg.XSDs, log, trace, wantDump, doCov) if err != nil { return err } @@ -228,6 +229,14 @@ func (i input) run(env v2.Context, src *source, cursor map[string]interface{}, p ) // Keep track of whether CEL is degraded for this periodic run. var isDegraded bool + if doCov { + defer func() { + // If doCov is true, log the updated coverage details. + // Updates are a running aggregate for each call to run + // as cov is shared via the program compilation. + log.Debugw("coverage", "details", cov.Details()) + }() + } for { if wait := time.Until(waitUntil); wait > 0 { // We have a special-case wait for when we have a zero limit. @@ -1039,10 +1048,10 @@ func getEnv(allowed []string) map[string]string { return env } -func newProgram(ctx context.Context, src, root string, vars map[string]string, client *http.Client, limiter *rate.Limiter, auth *lib.BasicAuth, patterns map[string]*regexp.Regexp, xsd map[string]string, log *logp.Logger, trace *httplog.LoggingRoundTripper, details bool) (cel.Program, *cel.Ast, error) { +func newProgram(ctx context.Context, src, root string, vars map[string]string, client *http.Client, limiter *rate.Limiter, auth *lib.BasicAuth, patterns map[string]*regexp.Regexp, xsd map[string]string, log *logp.Logger, trace *httplog.LoggingRoundTripper, details, coverage bool) (cel.Program, *cel.Ast, *lib.Coverage, error) { xml, err := lib.XML(nil, xsd) if err != nil { - return nil, nil, fmt.Errorf("failed to build xml type hints: %w", err) + return nil, nil, nil, fmt.Errorf("failed to build xml type hints: %w", err) } opts := []cel.EnvOption{ cel.Declarations(decls.NewVar(root, decls.Dyn)), @@ -1070,23 +1079,30 @@ func newProgram(ctx context.Context, src, root string, vars map[string]string, c } env, err := cel.NewEnv(opts...) if err != nil { - return nil, nil, fmt.Errorf("failed to create env: %w", err) + return nil, nil, nil, fmt.Errorf("failed to create env: %w", err) } ast, iss := env.Compile(src) if iss.Err() != nil { - return nil, nil, fmt.Errorf("failed compilation: %w", iss.Err()) + return nil, nil, nil, fmt.Errorf("failed compilation: %w", iss.Err()) } - var progOpts []cel.ProgramOption + var ( + progOpts []cel.ProgramOption + cov *lib.Coverage + ) + if coverage { + cov = lib.NewCoverage(ast) + progOpts = []cel.ProgramOption{cov.ProgramOption()} + } if details { progOpts = []cel.ProgramOption{cel.EvalOptions(cel.OptTrackState)} } prg, err := env.Program(ast, progOpts...) if err != nil { - return nil, nil, fmt.Errorf("failed program instantiation: %w", err) + return nil, nil, nil, fmt.Errorf("failed program instantiation: %w", err) } - return prg, ast, nil + return prg, ast, cov, nil } func debug(log *logp.Logger, trace *httplog.LoggingRoundTripper) func(string, any) { diff --git a/x-pack/filebeat/input/cel/input_test.go b/x-pack/filebeat/input/cel/input_test.go index 143402d98347..7ccfb9ccbee2 100644 --- a/x-pack/filebeat/input/cel/input_test.go +++ b/x-pack/filebeat/input/cel/input_test.go @@ -1769,6 +1769,49 @@ var inputTests = []struct { }, }, + // Coverage + { + name: "coverage", + config: map[string]interface{}{ + "interval": 1, + "program": `int(state.n).as(n, { + "events": [{"n": n+1}], + "n": n+1, + "want_more": n+1 < 5, + "probe": n < 2 ? + "little" + : + "big", + "fail_probe": n < 0 ? + "negative" + : + "non-negative", + })`, + "record_coverage": true, + "state": map[string]any{"n": 0}, + "resource": map[string]interface{}{ + "url": "", + }, + }, + time: func() time.Time { return time.Date(2010, 2, 9, 0, 0, 0, 0, time.UTC) }, + // The program will be evaluated five times in the first periodic + // run and then once for all subsequent runs. We depend here on + // the test construction that asks that we get at least as many + // results from the input as there are elements in the want slice + // and then stop. + want: []map[string]interface{}{ + // First periodic run. + {"n": float64(1)}, + {"n": float64(2)}, + {"n": float64(3)}, + {"n": float64(4)}, + {"n": float64(5)}, + // Second and subsequent periodic runs. + {"n": float64(6)}, + {"n": float64(7)}, + }, + }, + // not yet done from httpjson (some are redundant since they are compositional products). // // cursor/pagination (place above auth test block) From a64168707adea12f408773f018f4d549d0a23106 Mon Sep 17 00:00:00 2001 From: Dan Kortschak Date: Mon, 9 Dec 2024 07:45:33 +1030 Subject: [PATCH 25/48] x-pack/filebeat/input/httpjson: redact authorization headers in logging (#41920) This requires a small duplication of the mapstr.M API to workaround an issue in that type that can result in corruption of data. --- CHANGELOG.next.asciidoc | 1 + x-pack/filebeat/input/httpjson/input.go | 56 +++++++++++++++++++++++ x-pack/filebeat/input/httpjson/request.go | 2 +- 3 files changed, 58 insertions(+), 1 deletion(-) diff --git a/CHANGELOG.next.asciidoc b/CHANGELOG.next.asciidoc index 466cfa7e6232..aacf702a4db3 100644 --- a/CHANGELOG.next.asciidoc +++ b/CHANGELOG.next.asciidoc @@ -189,6 +189,7 @@ https://github.com/elastic/beats/compare/v8.8.1\...main[Check the HEAD diff] - Improve S3 object size metric calculation to support situations where Content-Length is not available. {pull}41755[41755] - Fix handling of http_endpoint request exceeding memory limits. {issue}41764[41764] {pull}41765[41765] - Rate limiting fixes in the Okta provider of the Entity Analytics input. {issue}40106[40106] {pull}41583[41583] +- Redact authorization headers in HTTPJSON debug logs. {pull}41920[41920] *Heartbeat* diff --git a/x-pack/filebeat/input/httpjson/input.go b/x-pack/filebeat/input/httpjson/input.go index ad61aceff895..51a9d446f472 100644 --- a/x-pack/filebeat/input/httpjson/input.go +++ b/x-pack/filebeat/input/httpjson/input.go @@ -15,6 +15,7 @@ import ( "net/url" "os" "path/filepath" + "sort" "strings" "time" @@ -33,6 +34,7 @@ import ( "github.com/elastic/beats/v7/libbeat/version" "github.com/elastic/beats/v7/x-pack/filebeat/input/internal/httplog" "github.com/elastic/beats/v7/x-pack/filebeat/input/internal/httpmon" + "github.com/elastic/beats/v7/x-pack/filebeat/input/internal/private" "github.com/elastic/elastic-agent-libs/logp" "github.com/elastic/elastic-agent-libs/mapstr" "github.com/elastic/elastic-agent-libs/monitoring" @@ -91,6 +93,60 @@ func Plugin(log *logp.Logger, store inputcursor.StateStore) v2.Plugin { } } +type redact struct { + value mapstrM + fields []string +} + +func (r redact) MarshalLogObject(enc zapcore.ObjectEncoder) error { + v, err := private.Redact(r.value, "", r.fields) + if err != nil { + return fmt.Errorf("could not redact value: %v", err) + } + return v.MarshalLogObject(enc) +} + +// mapstrM is a non-mutating version of mapstr.M. +// See https://github.com/elastic/elastic-agent-libs/issues/232. +type mapstrM mapstr.M + +// MarshalLogObject implements the zapcore.ObjectMarshaler interface and allows +// for more efficient marshaling of mapstrM in structured logging. +func (m mapstrM) MarshalLogObject(enc zapcore.ObjectEncoder) error { + if len(m) == 0 { + return nil + } + + keys := make([]string, 0, len(m)) + for k := range m { + keys = append(keys, k) + } + sort.Strings(keys) + for _, k := range keys { + v := m[k] + if inner, ok := tryToMapStr(v); ok { + err := enc.AddObject(k, inner) + if err != nil { + return fmt.Errorf("failed to add object: %w", err) + } + continue + } + zap.Any(k, v).AddTo(enc) + } + return nil +} + +func tryToMapStr(v interface{}) (mapstrM, bool) { + switch m := v.(type) { + case mapstrM: + return m, true + case map[string]interface{}: + return mapstrM(m), true + default: + return nil, false + } +} + func test(url *url.URL) error { port := func() string { if url.Port() != "" { diff --git a/x-pack/filebeat/input/httpjson/request.go b/x-pack/filebeat/input/httpjson/request.go index 160ac67fe9e6..fb847570826a 100644 --- a/x-pack/filebeat/input/httpjson/request.go +++ b/x-pack/filebeat/input/httpjson/request.go @@ -465,7 +465,7 @@ func (rf *requestFactory) newRequest(ctx *transformContext) (transformable, erro } } - rf.log.Debugf("new request: %#v", req) + rf.log.Debugw("new request", "req", redact{value: mapstrM(req), fields: []string{"header.Authorization"}}) return req, nil } From 2dbb60663c8e27698156faa7f8563662ce84a3aa Mon Sep 17 00:00:00 2001 From: Carson Ip Date: Mon, 9 Dec 2024 14:55:58 +0000 Subject: [PATCH 26/48] Remove ManagerV2 unnecessary reload when apm tracing config is nil (#41794) Remove unnecessary reload due to apm tracing config change in ManagerV2 when apm tracing config changes from nil to nil. --- CHANGELOG.next.asciidoc | 1 + x-pack/libbeat/management/managerV2.go | 13 +- x-pack/libbeat/management/managerV2_test.go | 148 +++++++++++++++++++- 3 files changed, 152 insertions(+), 10 deletions(-) diff --git a/CHANGELOG.next.asciidoc b/CHANGELOG.next.asciidoc index aacf702a4db3..76bc04ede5dd 100644 --- a/CHANGELOG.next.asciidoc +++ b/CHANGELOG.next.asciidoc @@ -115,6 +115,7 @@ https://github.com/elastic/beats/compare/v8.8.1\...main[Check the HEAD diff] - Ensure Elasticsearch output can always recover from network errors {pull}40794[40794] - Add `translate_ldap_attribute` processor. {pull}41472[41472] - Remove unnecessary debug logs during idle connection teardown {issue}40824[40824] +- Remove unnecessary reload for Elastic Agent managed beats when apm tracing config changes from nil to nil {pull}41794[41794] - Fix incorrect cloud provider identification in add_cloud_metadata processor using provider priority mechanism {pull}41636[41636] - Prevent panic if libbeat processors are loaded more than once. {issue}41475[41475] {pull}41857[51857] - Fix a bug where log files are rotated on startup when interval is configured and rotateonstartup is disabled {issue}41894[41894] {pull}41895[41895] diff --git a/x-pack/libbeat/management/managerV2.go b/x-pack/libbeat/management/managerV2.go index e39b394bf2b3..288f28ae0de5 100644 --- a/x-pack/libbeat/management/managerV2.go +++ b/x-pack/libbeat/management/managerV2.go @@ -893,6 +893,13 @@ func (cm *BeatV2Manager) reloadAPM(unit *agentUnit) { apmConfig = expected.APMConfig } } + + if (cm.lastAPMCfg == nil && apmConfig == nil) || (cm.lastAPMCfg != nil && gproto.Equal(cm.lastAPMCfg, apmConfig)) { + // configuration for the APM tracing did not change; do nothing + cm.logger.Debug("Skipped reloading APM tracing; configuration didn't change") + return + } + if apmConfig == nil { // APM tracing is being stopped cm.logger.Debug("Stopping APM tracing") @@ -907,12 +914,6 @@ func (cm *BeatV2Manager) reloadAPM(unit *agentUnit) { return } - if cm.lastAPMCfg != nil && gproto.Equal(cm.lastAPMCfg, apmConfig) { - // configuration for the APM tracing did not change; do nothing - cm.logger.Debug("Skipped reloading APM tracing; configuration didn't change") - return - } - uconfig, err := conf.NewConfigFrom(apmConfig) if err != nil { cm.logger.Errorf("Failed to create uconfig from APM configuration: %s", err) diff --git a/x-pack/libbeat/management/managerV2_test.go b/x-pack/libbeat/management/managerV2_test.go index f1b32b15d82d..e7515266b0bc 100644 --- a/x-pack/libbeat/management/managerV2_test.go +++ b/x-pack/libbeat/management/managerV2_test.go @@ -13,6 +13,7 @@ import ( "time" "github.com/joeshaw/multierror" + "github.com/stretchr/testify/assert" "github.com/stretchr/testify/require" "go.uber.org/zap/zapcore" "google.golang.org/grpc" @@ -266,6 +267,141 @@ func TestManagerV2(t *testing.T) { }, 15*time.Second, 300*time.Millisecond) } +func TestManagerV2_ReloadCount(t *testing.T) { + r := reload.NewRegistry() + + output := &reloadable{} + r.MustRegisterOutput(output) + inputs := &reloadableList{} + r.MustRegisterInput(inputs) + apm := &reloadable{} + r.MustRegisterAPM(apm) + + inputConfigUpdated := make(chan struct{}) + onObserved := func(observed *proto.CheckinObserved, currentIdx int) { + if currentIdx == 1 { + period, err := inputs.Configs()[0].Config.String("period", -1) + require.NoError(t, err) + if period == "10m" { + select { + case <-inputConfigUpdated: + default: + close(inputConfigUpdated) + } + } + } + } + + agentInfo := &proto.AgentInfo{ + Id: "elastic-agent-id", + Version: version.GetDefaultVersion(), + Snapshot: true, + } + srv := integration.NewMockServer([]*proto.CheckinExpected{ + { + AgentInfo: agentInfo, + Units: []*proto.UnitExpected{ + { + Id: "output-unit", + Type: proto.UnitType_OUTPUT, + ConfigStateIdx: 1, + Config: &proto.UnitExpectedConfig{ + Id: "default", + Type: "elasticsearch", + Name: "elasticsearch", + }, + State: proto.State_HEALTHY, + LogLevel: proto.UnitLogLevel_INFO, + }, + { + Id: "input-unit-1", + Type: proto.UnitType_INPUT, + ConfigStateIdx: 1, + Config: &proto.UnitExpectedConfig{ + Id: "system/metrics-system-default-system-1", + Type: "system/metrics", + Name: "system-1", + Streams: []*proto.Stream{ + { + Id: "system/metrics-system.filesystem-default-system-1", + Source: integration.RequireNewStruct(t, map[string]interface{}{ + "metricsets": []interface{}{"filesystem"}, + "period": "1m", + }), + }, + }, + }, + State: proto.State_HEALTHY, + LogLevel: proto.UnitLogLevel_INFO, + }, + }, + Features: nil, + FeaturesIdx: 1, + }, + { + AgentInfo: agentInfo, + Units: []*proto.UnitExpected{ + { + Id: "output-unit", + Type: proto.UnitType_OUTPUT, + ConfigStateIdx: 1, + State: proto.State_HEALTHY, + LogLevel: proto.UnitLogLevel_INFO, + }, + { + Id: "input-unit-1", + Type: proto.UnitType_INPUT, + ConfigStateIdx: 2, + Config: &proto.UnitExpectedConfig{ + Id: "system/metrics-system-default-system-1", + Type: "system/metrics", + Name: "system-1", + Streams: []*proto.Stream{ + { + Id: "system/metrics-system.filesystem-default-system-1", + Source: integration.RequireNewStruct(t, map[string]interface{}{ + "metricsets": []interface{}{"filesystem"}, + "period": "10m", + }), + }, + }, + }, + State: proto.State_HEALTHY, + LogLevel: proto.UnitLogLevel_INFO, + }, + }, + Features: nil, + FeaturesIdx: 1, + }, + }, + onObserved, + 500*time.Millisecond, + ) + require.NoError(t, srv.Start()) + defer srv.Stop() + + client := client.NewV2(fmt.Sprintf(":%d", srv.Port), "", client.VersionInfo{ + Name: "program", + Meta: map[string]string{ + "key": "value", + }, + }, client.WithGRPCDialOptions(grpc.WithTransportCredentials(insecure.NewCredentials()))) + + m, err := NewV2AgentManagerWithClient(&Config{ + Enabled: true, + }, r, client) + require.NoError(t, err) + + err = m.Start() + require.NoError(t, err) + defer m.Stop() + + <-inputConfigUpdated + assert.Equal(t, 1, output.reloadCount) // initial load + assert.Equal(t, 2, inputs.reloadCount) // initial load + config update + assert.Equal(t, 0, apm.reloadCount) // no apm tracing config applied +} + func TestOutputError(t *testing.T) { // Uncomment the line below to see the debug logs for this test // logp.DevelopmentSetup(logp.WithLevel(logp.DebugLevel), logp.WithSelectors("*")) @@ -553,19 +689,22 @@ func TestErrorPerUnit(t *testing.T) { } type reloadable struct { - mx sync.Mutex - config *reload.ConfigWithMeta + mx sync.Mutex + config *reload.ConfigWithMeta + reloadCount int } type reloadableList struct { - mx sync.Mutex - configs []*reload.ConfigWithMeta + mx sync.Mutex + configs []*reload.ConfigWithMeta + reloadCount int } func (r *reloadable) Reload(config *reload.ConfigWithMeta) error { r.mx.Lock() defer r.mx.Unlock() r.config = config + r.reloadCount++ return nil } @@ -579,6 +718,7 @@ func (r *reloadableList) Reload(configs []*reload.ConfigWithMeta) error { r.mx.Lock() defer r.mx.Unlock() r.configs = configs + r.reloadCount++ return nil } From 0827467636d1b22b4118968c15acdeff2937456f Mon Sep 17 00:00:00 2001 From: "Alex K." <8418476+fearful-symmetry@users.noreply.github.com> Date: Mon, 9 Dec 2024 07:31:17 -0800 Subject: [PATCH 27/48] Let network processor handle multiple IPs (#41918) * let network processor handle multiple IPs * add changelog * linter... * fix linter, logs, changelog * linter... * linter... * linter... * update docs * whoops * simplify logic * docs, cleanup --- CHANGELOG.next.asciidoc | 1 + libbeat/conditions/conditions_test.go | 23 ++++++++++ libbeat/conditions/network.go | 61 +++++++++++++++----------- libbeat/conditions/network_test.go | 52 ++++++++++++++++++++++ libbeat/docs/processors-using.asciidoc | 13 ++++-- 5 files changed, 121 insertions(+), 29 deletions(-) diff --git a/CHANGELOG.next.asciidoc b/CHANGELOG.next.asciidoc index 76bc04ede5dd..bb6c4df0f627 100644 --- a/CHANGELOG.next.asciidoc +++ b/CHANGELOG.next.asciidoc @@ -118,6 +118,7 @@ https://github.com/elastic/beats/compare/v8.8.1\...main[Check the HEAD diff] - Remove unnecessary reload for Elastic Agent managed beats when apm tracing config changes from nil to nil {pull}41794[41794] - Fix incorrect cloud provider identification in add_cloud_metadata processor using provider priority mechanism {pull}41636[41636] - Prevent panic if libbeat processors are loaded more than once. {issue}41475[41475] {pull}41857[51857] +- Allow network condition to handle field values that are arrays of IP addresses. {pull}41918[41918] - Fix a bug where log files are rotated on startup when interval is configured and rotateonstartup is disabled {issue}41894[41894] {pull}41895[41895] *Auditbeat* diff --git a/libbeat/conditions/conditions_test.go b/libbeat/conditions/conditions_test.go index be74f0a7caa9..8abbb0694e73 100644 --- a/libbeat/conditions/conditions_test.go +++ b/libbeat/conditions/conditions_test.go @@ -105,6 +105,29 @@ var httpResponseTestEvent = &beat.Event{ }, } +var httpResponseEventIPList = &beat.Event{ + Timestamp: time.Now(), + Fields: mapstr.M{ + "@timestamp": "2024-12-05T09:51:23.642Z", + "ecs": mapstr.M{ + "version": "8.11.0", + }, + "host": mapstr.M{ + "hostname": "testhost", + "os": mapstr.M{ + "type": "linux", + "family": "debian", + "version": "11 (bullseye)", + "platform": "debian", + }, + "ip": []string{ + "10.1.0.55", + "fe80::4001:aff:fe9a:55", + }, + }, + }, +} + func testConfig(t *testing.T, expected bool, event *beat.Event, config *Config) { t.Helper() logp.TestingSetup() diff --git a/libbeat/conditions/network.go b/libbeat/conditions/network.go index 76ab2d08423c..25c5fb86e701 100644 --- a/libbeat/conditions/network.go +++ b/libbeat/conditions/network.go @@ -20,6 +20,7 @@ package conditions import ( "fmt" "net" + "slices" "strings" "github.com/elastic/elastic-agent-libs/logp" @@ -94,6 +95,24 @@ func (m multiNetworkMatcher) String() string { return strings.Join(names, " OR ") } +func makeMatcher(network string) (networkMatcher, error) { + m := singleNetworkMatcher{name: network, netContainsFunc: namedNetworks[network]} + if m.netContainsFunc == nil { + subnet, err := parseCIDR(network) + if err != nil { + return nil, err + } + m.netContainsFunc = subnet.Contains + } + return m, nil +} + +func invalidTypeError(field string, value interface{}) error { + return fmt.Errorf("network condition attempted to set "+ + "'%v' -> '%v' and encountered unexpected type '%T', only "+ + "strings or []strings are allowed", field, value, value) +} + // NewNetworkCondition builds a new Network using the given configuration. func NewNetworkCondition(fields map[string]interface{}) (*Network, error) { cond := &Network{ @@ -101,24 +120,6 @@ func NewNetworkCondition(fields map[string]interface{}) (*Network, error) { log: logp.NewLogger(logName), } - makeMatcher := func(network string) (networkMatcher, error) { - m := singleNetworkMatcher{name: network, netContainsFunc: namedNetworks[network]} - if m.netContainsFunc == nil { - subnet, err := parseCIDR(network) - if err != nil { - return nil, err - } - m.netContainsFunc = subnet.Contains - } - return m, nil - } - - invalidTypeError := func(field string, value interface{}) error { - return fmt.Errorf("network condition attempted to set "+ - "'%v' -> '%v' and encountered unexpected type '%T', only "+ - "strings or []strings are allowed", field, value, value) - } - for field, value := range mapstr.M(fields).Flatten() { switch v := value.(type) { case string: @@ -157,15 +158,17 @@ func (c *Network) Check(event ValuesMap) bool { return false } - ip := extractIP(value) - if ip == nil { + ipList := extractIP(value) + if len(ipList) == 0 { c.log.Debugf("Invalid IP address in field=%v for network condition", field) return false } - - if !network.Contains(ip) { + // match on an "any" basis when we find multiple IPs in the event; + // if the network matcher returns true for any seen IP, consider it a match + if !slices.ContainsFunc(ipList, network.Contains) { return false } + } return true @@ -202,12 +205,20 @@ func parseCIDR(value string) (*net.IPNet, error) { // extractIP return an IP address if unk is an IP address string or a net.IP. // Otherwise it returns nil. -func extractIP(unk interface{}) net.IP { +func extractIP(unk interface{}) []net.IP { switch v := unk.(type) { case string: - return net.ParseIP(v) - case net.IP: + return []net.IP{net.ParseIP(v)} + case []net.IP: return v + case net.IP: + return []net.IP{v} + case []string: + parsed := make([]net.IP, len(v)) + for i, rawIP := range v { + parsed[i] = net.ParseIP(rawIP) + } + return parsed default: return nil } diff --git a/libbeat/conditions/network_test.go b/libbeat/conditions/network_test.go index b79568098e42..71ab0918e675 100644 --- a/libbeat/conditions/network_test.go +++ b/libbeat/conditions/network_test.go @@ -79,6 +79,26 @@ network: testYAMLConfig(t, true, evt, yaml) }) + + t.Run("IP list", func(t *testing.T) { + const yaml = ` +network: + ip: + client: [loopback] + server: [loopback] + host: 10.10.0.0/8 +` + + evt := &beat.Event{Fields: mapstr.M{ + "ip": mapstr.M{ + "client": "127.0.0.1", + "server": "127.0.0.1", + "host": []string{"10.10.0.83", "fe80::4001:aff:fe9a:53"}, + }, + }} + + testYAMLConfig(t, true, evt, yaml) + }) } func TestNetworkCreate(t *testing.T) { @@ -166,6 +186,22 @@ func TestNetworkCheck(t *testing.T) { }) }) + t.Run("multiple IPs field single match", func(t *testing.T) { + testConfig(t, true, httpResponseEventIPList, &Config{ + Network: map[string]interface{}{ + "host.ip": "10.1.0.0/24", + }, + }) + }) + + t.Run("multiple IPs field negative match", func(t *testing.T) { + testConfig(t, false, httpResponseEventIPList, &Config{ + Network: map[string]interface{}{ + "host.ip": "127.0.0.0/24", + }, + }) + }) + // Multiple conditions are treated as an implicit AND. t.Run("multiple fields negative match", func(t *testing.T) { testConfig(t, false, httpResponseTestEvent, &Config{ @@ -191,6 +227,22 @@ func TestNetworkCheck(t *testing.T) { }, }) }) + + t.Run("multiple values multiple IPs match", func(t *testing.T) { + testConfig(t, true, httpResponseEventIPList, &Config{ + Network: map[string]interface{}{ + "host.ip": []interface{}{"10.1.0.0/24", "127.0.0.0/24"}, + }, + }) + }) + + t.Run("multiple values multiple IPs no match", func(t *testing.T) { + testConfig(t, false, httpResponseEventIPList, &Config{ + Network: map[string]interface{}{ + "host.ip": []interface{}{"12.1.0.0/24", "127.0.0.0/24"}, + }, + }) + }) } func TestNetworkPrivate(t *testing.T) { diff --git a/libbeat/docs/processors-using.asciidoc b/libbeat/docs/processors-using.asciidoc index dd91ea8d5db6..a029f5f2ea8b 100644 --- a/libbeat/docs/processors-using.asciidoc +++ b/libbeat/docs/processors-using.asciidoc @@ -311,10 +311,15 @@ range: [[condition-network]] ===== `network` -The `network` condition checks if the field is in a certain IP network range. -Both IPv4 and IPv6 addresses are supported. The network range may be specified -using CIDR notation, like "192.0.2.0/24" or "2001:db8::/32", or by using one of -these named ranges: +The `network` condition checks whether a field's value falls within a specified +IP network range. If multiple fields are provided, each field value must match +its corresponding network range. You can specify multiple network ranges for a +single field, and a match occurs if any one of the ranges matches. If the field +value is an array of IPs, it will match if any of the IPs fall within any of the +given ranges. Both IPv4 and IPv6 addresses are supported. + +The network range may be specified using CIDR notation, like "192.0.2.0/24" or +"2001:db8::/32", or by using one of these named ranges: - `loopback` - Matches loopback addresses in the range of `127.0.0.0/8` or `::1/128`. From da6822b047abc974b153b5f9190345dd4983617d Mon Sep 17 00:00:00 2001 From: Lee E Hinman <57081003+leehinman@users.noreply.github.com> Date: Mon, 9 Dec 2024 09:58:17 -0600 Subject: [PATCH 28/48] Add unique per beat monitoring namespace (#41939) --- filebeat/beater/filebeat.go | 14 ++++++-- heartbeat/monitors/mocks.go | 9 ++--- libbeat/beat/info.go | 7 ++-- libbeat/cmd/instance/beat.go | 36 +++++++++++++------ x-pack/filebeat/input/benchmark/input.go | 10 +++--- .../scenarios/framework/framework.go | 23 ++++++------ 6 files changed, 60 insertions(+), 39 deletions(-) diff --git a/filebeat/beater/filebeat.go b/filebeat/beater/filebeat.go index ceab21aa3590..4909941b90ae 100644 --- a/filebeat/beater/filebeat.go +++ b/filebeat/beater/filebeat.go @@ -272,10 +272,18 @@ func (fb *Filebeat) Run(b *beat.Beat) error { waitEvents := newSignalWait() // count active events for waiting on shutdown + var reg *monitoring.Registry + + if b.Info.Monitoring.Namespace != nil { + reg = b.Info.Monitoring.Namespace.GetRegistry().GetRegistry("stats") + if reg == nil { + reg = b.Info.Monitoring.Namespace.GetRegistry().NewRegistry("stats") + } + } wgEvents := &eventCounter{ - count: monitoring.NewInt(nil, "filebeat.events.active"), // Gauge - added: monitoring.NewUint(nil, "filebeat.events.added"), - done: monitoring.NewUint(nil, "filebeat.events.done"), + count: monitoring.NewInt(reg, "filebeat.events.active"), // Gauge + added: monitoring.NewUint(reg, "filebeat.events.added"), + done: monitoring.NewUint(reg, "filebeat.events.done"), } finishedLogger := newFinishedLogger(wgEvents) diff --git a/heartbeat/monitors/mocks.go b/heartbeat/monitors/mocks.go index c172d24464c8..77dee19858a7 100644 --- a/heartbeat/monitors/mocks.go +++ b/heartbeat/monitors/mocks.go @@ -60,12 +60,8 @@ func makeMockFactory(pluginsReg *plugin.PluginsReg) (factory *RunnerFactory, sch EphemeralID: eid, FirstStart: time.Now(), StartTime: time.Now(), - Monitoring: struct { - DefaultUsername string - }{ - DefaultUsername: "test", - }, } + info.Monitoring.DefaultUsername = "test" sched = scheduler.Create( 1, @@ -246,7 +242,8 @@ func mockPluginBuilder() (plugin.PluginFactory, *atomic.Int, *atomic.Int) { return plugin.Plugin{Jobs: j, DoClose: closer, Endpoints: 1}, nil }, - Stats: plugin.NewPluginCountersRecorder("test", reg)}, + Stats: plugin.NewPluginCountersRecorder("test", reg), + }, built, closed } diff --git a/libbeat/beat/info.go b/libbeat/beat/info.go index 314597abbb56..7c3b5c0d90f8 100644 --- a/libbeat/beat/info.go +++ b/libbeat/beat/info.go @@ -22,6 +22,8 @@ import ( "github.com/gofrs/uuid/v5" "go.opentelemetry.io/collector/consumer" + + "github.com/elastic/elastic-agent-libs/monitoring" ) // Info stores a beats instance meta data. @@ -41,9 +43,10 @@ type Info struct { // Monitoring-related fields Monitoring struct { - DefaultUsername string // The default username to be used to connect to Elasticsearch Monitoring + DefaultUsername string // The default username to be used to connect to Elasticsearch Monitoring + Namespace *monitoring.Namespace // a monitor namespace that is unique per beat instance } - LogConsumer consumer.Logs //otel log consumer + LogConsumer consumer.Logs // otel log consumer } diff --git a/libbeat/cmd/instance/beat.go b/libbeat/cmd/instance/beat.go index 6332ebac39b5..2d1eb3a20f02 100644 --- a/libbeat/cmd/instance/beat.go +++ b/libbeat/cmd/instance/beat.go @@ -337,6 +337,8 @@ func NewBeatReceiver(settings Settings, receiverConfig map[string]interface{}, c config.OverwriteConfigOpts(configOpts(store)) } + b.Beat.Info.Monitoring.Namespace = monitoring.GetNamespace(b.Info.Beat + "-" + b.Info.ID.String()) + instrumentation, err := instrumentation.New(cfg, b.Info.Beat, b.Info.Version) if err != nil { return nil, fmt.Errorf("error setting up instrumentation: %w", err) @@ -469,11 +471,6 @@ func NewBeatReceiver(settings Settings, receiverConfig map[string]interface{}, c return nil, fmt.Errorf("error creating processors: %w", err) } - reg := monitoring.Default.GetRegistry(b.Info.Name) - if reg == nil { - reg = monitoring.Default.NewRegistry(b.Info.Name) - } - // This should be replaced with static config for otel consumer // but need to figure out if we want the Queue settings from here. outputEnabled := b.Config.Output.IsSet() && b.Config.Output.Config().Enabled() @@ -485,12 +482,14 @@ func NewBeatReceiver(settings Settings, receiverConfig map[string]interface{}, c } } - tel := reg.GetRegistry("state") + uniq_reg := b.Beat.Info.Monitoring.Namespace.GetRegistry() + + tel := uniq_reg.GetRegistry("state") if tel == nil { - tel = reg.NewRegistry("state") + tel = uniq_reg.NewRegistry("state") } monitors := pipeline.Monitors{ - Metrics: reg, + Metrics: uniq_reg, Telemetry: tel, Logger: logp.L().Named("publisher"), Tracer: b.Instrumentation.Tracer(), @@ -510,7 +509,6 @@ func NewBeatReceiver(settings Settings, receiverConfig map[string]interface{}, c b.Publisher = publisher return b, nil - } // InitWithSettings does initialization of things common to all actions (read confs, flags) @@ -831,11 +829,27 @@ func (b *Beat) RegisterHostname(useFQDN bool) { hostname := b.Info.FQDNAwareHostname(useFQDN) // info.hostname - infoRegistry := monitoring.GetNamespace("info").GetRegistry() + var infoRegistry *monitoring.Registry + if b.Info.Monitoring.Namespace != nil { + infoRegistry = b.Info.Monitoring.Namespace.GetRegistry().GetRegistry("info") + if infoRegistry == nil { + infoRegistry = b.Info.Monitoring.Namespace.GetRegistry().NewRegistry("info") + } + } else { + infoRegistry = monitoring.GetNamespace("info").GetRegistry() + } monitoring.NewString(infoRegistry, "hostname").Set(hostname) // state.host - stateRegistry := monitoring.GetNamespace("state").GetRegistry() + var stateRegistry *monitoring.Registry + if b.Info.Monitoring.Namespace != nil { + stateRegistry = b.Info.Monitoring.Namespace.GetRegistry().GetRegistry("state") + if stateRegistry == nil { + stateRegistry = b.Info.Monitoring.Namespace.GetRegistry().NewRegistry("state") + } + } else { + stateRegistry = monitoring.GetNamespace("state").GetRegistry() + } monitoring.NewFunc(stateRegistry, "host", host.ReportInfo(hostname), monitoring.Report) } diff --git a/x-pack/filebeat/input/benchmark/input.go b/x-pack/filebeat/input/benchmark/input.go index dd6d198cc409..e098d3e746bc 100644 --- a/x-pack/filebeat/input/benchmark/input.go +++ b/x-pack/filebeat/input/benchmark/input.go @@ -60,7 +60,7 @@ func (bi *benchmarkInput) Test(ctx v2.TestContext) error { // Run starts the data generation. func (bi *benchmarkInput) Run(ctx v2.Context, publisher stateless.Publisher) error { var wg sync.WaitGroup - metrics := newInputMetrics(ctx.ID) + metrics := newInputMetrics(ctx) for i := uint8(0); i < bi.cfg.Threads; i++ { wg.Add(1) @@ -103,8 +103,8 @@ func runThread(ctx v2.Context, publisher stateless.Publisher, thread uint8, cfg ticker.Stop() return case <-ticker.C: - //don't want to block on filling doPublish channel - //so only send as many as it can hold right now + // don't want to block on filling doPublish channel + // so only send as many as it can hold right now numToSend := cap(pubChan) - len(pubChan) for i := 0; i < numToSend; i++ { pubChan <- true @@ -157,8 +157,8 @@ type inputMetrics struct { } // newInputMetrics returns an input metric for the benchmark processor. -func newInputMetrics(id string) *inputMetrics { - reg, unreg := inputmon.NewInputRegistry(inputName, id, nil) +func newInputMetrics(ctx v2.Context) *inputMetrics { + reg, unreg := inputmon.NewInputRegistry(inputName, ctx.ID, ctx.Agent.Monitoring.Namespace.GetRegistry()) out := &inputMetrics{ unregister: unreg, eventsPublished: monitoring.NewUint(reg, "events_published_total"), diff --git a/x-pack/heartbeat/scenarios/framework/framework.go b/x-pack/heartbeat/scenarios/framework/framework.go index a2fb77e63070..6119f549e997 100644 --- a/x-pack/heartbeat/scenarios/framework/framework.go +++ b/x-pack/heartbeat/scenarios/framework/framework.go @@ -30,11 +30,13 @@ import ( beatversion "github.com/elastic/beats/v7/libbeat/version" ) -type ScenarioRun func(t *testing.T) (config mapstr.M, meta ScenarioRunMeta, close func(), err error) -type ScenarioRunMeta struct { - URL *url.URL - Status monitorstate.StateStatus -} +type ( + ScenarioRun func(t *testing.T) (config mapstr.M, meta ScenarioRunMeta, close func(), err error) + ScenarioRunMeta struct { + URL *url.URL + Status monitorstate.StateStatus + } +) type Scenario struct { Name string @@ -155,7 +157,6 @@ func NewScenarioDB() *ScenarioDB { ByTag: map[string][]Scenario{}, All: []Scenario{}, } - } func (sdb *ScenarioDB) Init() { @@ -250,7 +251,9 @@ func runMonitorOnce(t *testing.T, monitorConfig mapstr.M, meta ScenarioRunMeta, mIface, err := f.Create(pipe, conf) require.NoError(t, err) - mtr.monitor = mIface.(*monitors.Monitor) + mon, ok := mIface.(*monitors.Monitor) + require.True(t, ok, "type assertion didn't succeed") + mtr.monitor = mon require.NotNil(t, mtr.monitor, "could not convert to monitor %v", mIface) mtr.Events = pipe.PublishedEvents @@ -281,12 +284,8 @@ func setupFactoryAndSched(location *hbconfig.LocationWithID, stateLoader monitor EphemeralID: eid, FirstStart: time.Now(), StartTime: time.Now(), - Monitoring: struct { - DefaultUsername string - }{ - DefaultUsername: "test", - }, } + info.Monitoring.DefaultUsername = "test" sched = scheduler.Create( 1, From f86a5f07fbeab811f6e8c80f0350c2b7be873603 Mon Sep 17 00:00:00 2001 From: Mauri de Souza Meneguzzo Date: Mon, 9 Dec 2024 14:37:33 -0300 Subject: [PATCH 29/48] metricbeat: handle nf_conntrack module not loaded in linux integration (#41930) * metricbeat: handle nf_conntrack module not loaded in linux integration * ci lint fixes * fix error check to prevent windows failure --- .../module/linux/conntrack/conntrack.go | 9 +++++++- .../module/linux/conntrack/conntrack_test.go | 22 +++++++++++++++++++ 2 files changed, 30 insertions(+), 1 deletion(-) diff --git a/metricbeat/module/linux/conntrack/conntrack.go b/metricbeat/module/linux/conntrack/conntrack.go index 602a786b5742..42c2114f92ce 100644 --- a/metricbeat/module/linux/conntrack/conntrack.go +++ b/metricbeat/module/linux/conntrack/conntrack.go @@ -19,6 +19,7 @@ package conntrack import ( "fmt" + "os" "github.com/prometheus/procfs" @@ -50,7 +51,10 @@ type MetricSet struct { func New(base mb.BaseMetricSet) (mb.MetricSet, error) { cfgwarn.Beta("The linux conntrack metricset is beta.") - sys := base.Module().(resolve.Resolver) + sys, ok := base.Module().(resolve.Resolver) + if !ok { + return nil, fmt.Errorf("unexpected module type: %T", base.Module()) + } return &MetricSet{ BaseMetricSet: base, @@ -68,6 +72,9 @@ func (m *MetricSet) Fetch(report mb.ReporterV2) error { } conntrackStats, err := newFS.ConntrackStat() if err != nil { + if os.IsNotExist(err) { + err = mb.PartialMetricsError{Err: fmt.Errorf("nf_conntrack kernel module not loaded: %w", err)} + } return fmt.Errorf("error fetching conntrack stats: %w", err) } diff --git a/metricbeat/module/linux/conntrack/conntrack_test.go b/metricbeat/module/linux/conntrack/conntrack_test.go index cc3b2a052306..0d1ad2a46775 100644 --- a/metricbeat/module/linux/conntrack/conntrack_test.go +++ b/metricbeat/module/linux/conntrack/conntrack_test.go @@ -18,10 +18,15 @@ package conntrack import ( + "errors" + "os" + "path/filepath" "testing" "github.com/stretchr/testify/assert" + "github.com/stretchr/testify/require" + "github.com/elastic/beats/v7/metricbeat/mb" mbtest "github.com/elastic/beats/v7/metricbeat/mb/testing" _ "github.com/elastic/beats/v7/metricbeat/module/linux" "github.com/elastic/elastic-agent-libs/mapstr" @@ -60,6 +65,23 @@ func TestFetch(t *testing.T) { assert.Equal(t, testConn, rawEvent) } +func TestFetchConntrackModuleNotLoaded(t *testing.T) { + // Create a temporary directory to simulate a missing /proc/net/stat/nf_conntrack file + tmpDir := t.TempDir() + assert.NoError(t, os.MkdirAll(filepath.Join(tmpDir, "proc/net/stat"), 0755)) + c := getConfig() + c["hostfs"] = tmpDir + + f := mbtest.NewReportingMetricSetV2Error(t, c) + events, errs := mbtest.ReportingFetchV2Error(f) + + require.Len(t, errs, 1) + err := errors.Join(errs...) + assert.ErrorAs(t, err, &mb.PartialMetricsError{}) + assert.Contains(t, err.Error(), "error fetching conntrack stats: nf_conntrack kernel module not loaded") + require.Empty(t, events) +} + func getConfig() map[string]interface{} { return map[string]interface{}{ "module": "linux", From 1fefdbb2c26128c18e339a78866d4b756548b6c2 Mon Sep 17 00:00:00 2001 From: Michael Katsoulis Date: Tue, 10 Dec 2024 11:37:49 +0200 Subject: [PATCH 30/48] Add support for podman metrics in docker module (#41889) * Add support for podman metrics --- metricbeat/docs/modules/docker.asciidoc | 9 +++++ metricbeat/metricbeat.reference.yml | 3 ++ .../module/docker/_meta/config.reference.yml | 3 ++ metricbeat/module/docker/_meta/config.yml | 3 ++ metricbeat/module/docker/_meta/docs.asciidoc | 6 +++ metricbeat/module/docker/config.go | 8 ++-- metricbeat/module/docker/cpu/cpu.go | 4 +- metricbeat/module/docker/diskio/diskio.go | 2 +- metricbeat/module/docker/docker.go | 40 +++++++++++++++---- metricbeat/module/docker/memory/memory.go | 4 +- metricbeat/module/docker/network/network.go | 2 +- .../docker/network_summary/network_summary.go | 2 +- metricbeat/modules.d/docker.yml.disabled | 3 ++ x-pack/metricbeat/metricbeat.reference.yml | 3 ++ 14 files changed, 76 insertions(+), 16 deletions(-) diff --git a/metricbeat/docs/modules/docker.asciidoc b/metricbeat/docs/modules/docker.asciidoc index cd5e2a207a83..a8ae9cbf4882 100644 --- a/metricbeat/docs/modules/docker.asciidoc +++ b/metricbeat/docs/modules/docker.asciidoc @@ -22,6 +22,9 @@ The Docker module is currently tested on Linux and Mac with the community edition engine, versions 1.11 and 17.09.0-ce. It is not tested on Windows, but it should also work there. +The Docker module supports collection of metrics from Podman's Docker-compatible API. +It has been tested on Linux and Mac with Podman Rest API v2.0.0 and above. + [float] === Module-specific configuration notes @@ -30,6 +33,9 @@ It is strongly recommended that you run Docker metricsets with a Docker API already takes up to 2 seconds. Specifying less than 3 seconds will result in requests that timeout, and no data will be reported for those requests. +In the case of Podman, the configuration parameter `podman` should be set to `true`. +This enables streaming of container stats output, which allows for more accurate +CPU percentage calculations when using Podman. :edit_url: @@ -62,6 +68,9 @@ metricbeat.modules: # If set to true, replace dots in labels with `_`. #labels.dedot: false + # Docker module supports metrics collection from podman's docker compatible API. In case of podman set to true. + # podman: false + # Skip metrics for certain device major numbers in docker/diskio. # Necessary on systems with software RAID, device mappers, # or other configurations where virtual disks will sum metrics from other disks. diff --git a/metricbeat/metricbeat.reference.yml b/metricbeat/metricbeat.reference.yml index 0a05e0c6008b..f1412be4b6f2 100644 --- a/metricbeat/metricbeat.reference.yml +++ b/metricbeat/metricbeat.reference.yml @@ -268,6 +268,9 @@ metricbeat.modules: # If set to true, replace dots in labels with `_`. #labels.dedot: false + # Docker module supports metrics collection from podman's docker compatible API. In case of podman set to true. + # podman: false + # Skip metrics for certain device major numbers in docker/diskio. # Necessary on systems with software RAID, device mappers, # or other configurations where virtual disks will sum metrics from other disks. diff --git a/metricbeat/module/docker/_meta/config.reference.yml b/metricbeat/module/docker/_meta/config.reference.yml index 8d11201983cf..184d6592bf17 100644 --- a/metricbeat/module/docker/_meta/config.reference.yml +++ b/metricbeat/module/docker/_meta/config.reference.yml @@ -17,6 +17,9 @@ # If set to true, replace dots in labels with `_`. #labels.dedot: false + # Docker module supports metrics collection from podman's docker compatible API. In case of podman set to true. + # podman: false + # Skip metrics for certain device major numbers in docker/diskio. # Necessary on systems with software RAID, device mappers, # or other configurations where virtual disks will sum metrics from other disks. diff --git a/metricbeat/module/docker/_meta/config.yml b/metricbeat/module/docker/_meta/config.yml index da3c1e02a068..a7b9b9196fca 100644 --- a/metricbeat/module/docker/_meta/config.yml +++ b/metricbeat/module/docker/_meta/config.yml @@ -15,6 +15,9 @@ # If set to true, replace dots in labels with `_`. #labels.dedot: false + # Docker module supports metrics collection from podman's Docker-compatible API. In case of podman set to true. + # podman: false + # Skip metrics for certain device major numbers in docker/diskio. # Necessary on systems with software RAID, device mappers, # or other configurations where virtual disks will sum metrics from other disks. diff --git a/metricbeat/module/docker/_meta/docs.asciidoc b/metricbeat/module/docker/_meta/docs.asciidoc index e1d5437572a4..ca2da0ea26dc 100644 --- a/metricbeat/module/docker/_meta/docs.asciidoc +++ b/metricbeat/module/docker/_meta/docs.asciidoc @@ -11,6 +11,9 @@ The Docker module is currently tested on Linux and Mac with the community edition engine, versions 1.11 and 17.09.0-ce. It is not tested on Windows, but it should also work there. +The Docker module supports collection of metrics from Podman's Docker-compatible API. +It has been tested on Linux and Mac with Podman Rest API v2.0.0 and above. + [float] === Module-specific configuration notes @@ -19,3 +22,6 @@ It is strongly recommended that you run Docker metricsets with a Docker API already takes up to 2 seconds. Specifying less than 3 seconds will result in requests that timeout, and no data will be reported for those requests. +In the case of Podman, the configuration parameter `podman` should be set to `true`. +This enables streaming of container stats output, which allows for more accurate +CPU percentage calculations when using Podman. diff --git a/metricbeat/module/docker/config.go b/metricbeat/module/docker/config.go index 40698cb0baf9..b9bee9b35e9d 100644 --- a/metricbeat/module/docker/config.go +++ b/metricbeat/module/docker/config.go @@ -19,14 +19,16 @@ package docker // Config contains the config needed for the docker type Config struct { - TLS *TLSConfig `config:"ssl"` - DeDot bool `config:"labels.dedot"` + TLS *TLSConfig `config:"ssl"` + DeDot bool `config:"labels.dedot"` + Podman bool `config:"podman"` } // DefaultConfig returns default module config func DefaultConfig() Config { return Config{ - DeDot: true, + DeDot: true, + Podman: false, } } diff --git a/metricbeat/module/docker/cpu/cpu.go b/metricbeat/module/docker/cpu/cpu.go index a29ee8a00cc2..6869dd30a461 100644 --- a/metricbeat/module/docker/cpu/cpu.go +++ b/metricbeat/module/docker/cpu/cpu.go @@ -40,6 +40,7 @@ type MetricSet struct { cpuService *CPUService dockerClient *client.Client dedot bool + podman bool } // New creates a new instance of the docker cpu MetricSet. @@ -68,12 +69,13 @@ func New(base mb.BaseMetricSet) (mb.MetricSet, error) { dockerClient: client, cpuService: &CPUService{Cores: cpuConfig.Cores}, dedot: config.DeDot, + podman: config.Podman, }, nil } // Fetch returns a list of docker CPU stats. func (m *MetricSet) Fetch(r mb.ReporterV2) error { - stats, err := docker.FetchStats(m.dockerClient, m.Module().Config().Timeout) + stats, err := docker.FetchStats(m.dockerClient, m.Module().Config().Timeout, m.podman, m.Logger()) if err != nil { return fmt.Errorf("failed to get docker stats: %w", err) } diff --git a/metricbeat/module/docker/diskio/diskio.go b/metricbeat/module/docker/diskio/diskio.go index df5a0f2dff51..a59de2d52683 100644 --- a/metricbeat/module/docker/diskio/diskio.go +++ b/metricbeat/module/docker/diskio/diskio.go @@ -89,7 +89,7 @@ func New(base mb.BaseMetricSet) (mb.MetricSet, error) { // Fetch creates list of events with diskio stats for all containers. func (m *MetricSet) Fetch(r mb.ReporterV2) error { - stats, err := docker.FetchStats(m.dockerClient, m.Module().Config().Timeout) + stats, err := docker.FetchStats(m.dockerClient, m.Module().Config().Timeout, false, m.Logger()) if err != nil { return fmt.Errorf("failed to get docker stats: %w", err) } diff --git a/metricbeat/module/docker/docker.go b/metricbeat/module/docker/docker.go index 2020df91975b..d4595ef8e5ed 100644 --- a/metricbeat/module/docker/docker.go +++ b/metricbeat/module/docker/docker.go @@ -34,6 +34,7 @@ import ( "github.com/elastic/beats/v7/metricbeat/mb" "github.com/elastic/beats/v7/metricbeat/mb/parse" "github.com/elastic/elastic-agent-autodiscover/docker" + "github.com/elastic/elastic-agent-libs/logp" ) // HostParser is a TCP host parser function for docker tcp host addresses @@ -91,7 +92,7 @@ func NewDockerClient(endpoint string, config Config) (*client.Client, error) { } // FetchStats returns a list of running containers with all related stats inside -func FetchStats(client *client.Client, timeout time.Duration) ([]Stat, error) { +func FetchStats(client *client.Client, timeout time.Duration, stream bool, logger *logp.Logger) ([]Stat, error) { ctx, cancel := context.WithTimeout(context.Background(), timeout) defer cancel() containers, err := client.ContainerList(ctx, container.ListOptions{}) @@ -108,7 +109,7 @@ func FetchStats(client *client.Client, timeout time.Duration) ([]Stat, error) { for _, container := range containers { go func(container types.Container) { defer wg.Done() - statsQueue <- exportContainerStats(ctx, client, &container) + statsQueue <- exportContainerStats(ctx, client, &container, stream, logger) }(container) } @@ -133,18 +134,41 @@ func FetchStats(client *client.Client, timeout time.Duration) ([]Stat, error) { // This is currently very inefficient as docker calculates the average for each request, // means each request will take at least 2s: https://github.com/docker/docker/blob/master/cli/command/container/stats_helpers.go#L148 // Getting all stats at once is implemented here: https://github.com/docker/docker/pull/25361 -func exportContainerStats(ctx context.Context, client *client.Client, container *types.Container) Stat { +// In case stream is true, we use get a stream of results for container stats. From the stream we keep the second result. +// This is needed for podman use case where in case stream is false, no precpu stats are returned. The precpu stats +// are required for the cpu percentage calculation. We keep the second result as in the first result, the stats are not correct. +func exportContainerStats(ctx context.Context, client *client.Client, container *types.Container, stream bool, logger *logp.Logger) Stat { var event Stat event.Container = container - - containerStats, err := client.ContainerStats(ctx, container.ID, false) + containerStats, err := client.ContainerStats(ctx, container.ID, stream) if err != nil { + logger.Debugf("Failed fetching container stats: %v", err) return event } - defer containerStats.Body.Close() - decoder := json.NewDecoder(containerStats.Body) - decoder.Decode(&event.Stats) + // JSON decoder + decoder := json.NewDecoder(containerStats.Body) + if !stream { + if err := decoder.Decode(&event.Stats); err != nil { + logger.Debugf("Failed decoding event: %v", err) + return event + } + } else { + // handle stream. Take the second result. + count := 0 + for decoder.More() { + if err := decoder.Decode(&event.Stats); err != nil { + logger.Debugf("Failed decoding event: %v", err) + return event + } + + count++ + // Exit after the second result + if count == 2 { + break + } + } + } return event } diff --git a/metricbeat/module/docker/memory/memory.go b/metricbeat/module/docker/memory/memory.go index 140383de833e..5c90c09d39c2 100644 --- a/metricbeat/module/docker/memory/memory.go +++ b/metricbeat/module/docker/memory/memory.go @@ -43,6 +43,7 @@ type MetricSet struct { memoryService *MemoryService dockerClient *client.Client dedot bool + podman bool logger *logp.Logger } @@ -64,13 +65,14 @@ func New(base mb.BaseMetricSet) (mb.MetricSet, error) { memoryService: &MemoryService{}, dockerClient: dockerClient, dedot: config.DeDot, + podman: config.Podman, logger: logger, }, nil } // Fetch creates a list of memory events for each container. func (m *MetricSet) Fetch(r mb.ReporterV2) error { - stats, err := docker.FetchStats(m.dockerClient, m.Module().Config().Timeout) + stats, err := docker.FetchStats(m.dockerClient, m.Module().Config().Timeout, m.podman, m.Logger()) if err != nil { return fmt.Errorf("failed to get docker stats: %w", err) } diff --git a/metricbeat/module/docker/network/network.go b/metricbeat/module/docker/network/network.go index 8a70fd124466..34487aa49835 100644 --- a/metricbeat/module/docker/network/network.go +++ b/metricbeat/module/docker/network/network.go @@ -66,7 +66,7 @@ func New(base mb.BaseMetricSet) (mb.MetricSet, error) { // Fetch methods creates a list of network events for each container. func (m *MetricSet) Fetch(r mb.ReporterV2) error { - stats, err := docker.FetchStats(m.dockerClient, m.Module().Config().Timeout) + stats, err := docker.FetchStats(m.dockerClient, m.Module().Config().Timeout, false, m.Logger()) if err != nil { return fmt.Errorf("failed to get docker stats: %w", err) } diff --git a/metricbeat/module/docker/network_summary/network_summary.go b/metricbeat/module/docker/network_summary/network_summary.go index 9753b449adde..9052e38580b0 100644 --- a/metricbeat/module/docker/network_summary/network_summary.go +++ b/metricbeat/module/docker/network_summary/network_summary.go @@ -84,7 +84,7 @@ func New(base mb.BaseMetricSet) (mb.MetricSet, error) { // of an error set the Error field of mb.Event or simply call report.Error(). func (m *MetricSet) Fetch(ctx context.Context, report mb.ReporterV2) error { - stats, err := docker.FetchStats(m.dockerClient, m.Module().Config().Timeout) + stats, err := docker.FetchStats(m.dockerClient, m.Module().Config().Timeout, false, m.Logger()) if err != nil { return fmt.Errorf("failed to get docker stats: %w", err) } diff --git a/metricbeat/modules.d/docker.yml.disabled b/metricbeat/modules.d/docker.yml.disabled index 88af5d212889..726c535af1aa 100644 --- a/metricbeat/modules.d/docker.yml.disabled +++ b/metricbeat/modules.d/docker.yml.disabled @@ -18,6 +18,9 @@ # If set to true, replace dots in labels with `_`. #labels.dedot: false + # Docker module supports metrics collection from podman's Docker-compatible API. In case of podman set to true. + # podman: false + # Skip metrics for certain device major numbers in docker/diskio. # Necessary on systems with software RAID, device mappers, # or other configurations where virtual disks will sum metrics from other disks. diff --git a/x-pack/metricbeat/metricbeat.reference.yml b/x-pack/metricbeat/metricbeat.reference.yml index 8d3949ef666a..8c4250caecea 100644 --- a/x-pack/metricbeat/metricbeat.reference.yml +++ b/x-pack/metricbeat/metricbeat.reference.yml @@ -521,6 +521,9 @@ metricbeat.modules: # If set to true, replace dots in labels with `_`. #labels.dedot: false + # Docker module supports metrics collection from podman's docker compatible API. In case of podman set to true. + # podman: false + # Skip metrics for certain device major numbers in docker/diskio. # Necessary on systems with software RAID, device mappers, # or other configurations where virtual disks will sum metrics from other disks. From dbeb9cda93620f8c28f24e4b97b3033db93a2f7f Mon Sep 17 00:00:00 2001 From: Mauri de Souza Meneguzzo Date: Tue, 10 Dec 2024 09:09:22 -0300 Subject: [PATCH 31/48] otelconsumer: remove temporary handling of entity too large (#41911) This code was initially added in #41523 because of a limitation from the elasticsearch exporter. The elasticsearch exporter has been updated to enforce flush::max_bytes for the batcher extension and will automatically split the batch if it exceeds the limit. This error is now fixed in the collector v0.115.0. See https://github.com/open-telemetry/opentelemetry-collector-contrib/pull/36396. --- libbeat/outputs/otelconsumer/otelconsumer.go | 25 ----------------- .../outputs/otelconsumer/otelconsumer_test.go | 27 ------------------- 2 files changed, 52 deletions(-) diff --git a/libbeat/outputs/otelconsumer/otelconsumer.go b/libbeat/outputs/otelconsumer/otelconsumer.go index ca5da5308e59..7b2f6fe93e5f 100644 --- a/libbeat/outputs/otelconsumer/otelconsumer.go +++ b/libbeat/outputs/otelconsumer/otelconsumer.go @@ -20,7 +20,6 @@ package otelconsumer import ( "context" "fmt" - "strings" "time" "github.com/elastic/beats/v7/libbeat/beat" @@ -103,30 +102,6 @@ func (out *otelConsumer) logsPublish(ctx context.Context, batch publisher.Batch) err := out.logsConsumer.ConsumeLogs(ctx, pLogs) if err != nil { - // If the batch is too large, the elasticsearchexporter will - // return a 413 error. - // - // At the moment, the exporter does not support batch splitting - // on error so we do it here. - // - // See https://github.com/open-telemetry/opentelemetry-collector-contrib/issues/36163. - if strings.Contains(err.Error(), "Request Entity Too Large") { - // Try and split the batch into smaller batches and retry - if batch.SplitRetry() { - st.BatchSplit() - st.RetryableErrors(len(events)) - } else { - // If the batch could not be split, there is no option left but - // to drop it and log the error state. - batch.Drop() - st.PermanentErrors(len(events)) - out.log.Errorf("the batch is too large to be sent: %v", err) - } - - // Don't propagate the error, the batch was split and retried. - return nil - } - // Permanent errors shouldn't be retried. This tipically means // the data cannot be serialized by the exporter that is attached // to the pipeline or when the destination refuses the data because diff --git a/libbeat/outputs/otelconsumer/otelconsumer_test.go b/libbeat/outputs/otelconsumer/otelconsumer_test.go index 2751ce7f7214..6a197d806c13 100644 --- a/libbeat/outputs/otelconsumer/otelconsumer_test.go +++ b/libbeat/outputs/otelconsumer/otelconsumer_test.go @@ -90,33 +90,6 @@ func TestPublish(t *testing.T) { assert.Equal(t, outest.BatchRetry, batch.Signals[0].Tag) }) - t.Run("split batch on entity too large error", func(t *testing.T) { - batch := outest.NewBatch(event1, event2, event3) - - otelConsumer := makeOtelConsumer(t, func(ctx context.Context, ld plog.Logs) error { - return errors.New("Request Entity Too Large") - }) - - err := otelConsumer.Publish(ctx, batch) - assert.NoError(t, err) - assert.Len(t, batch.Signals, 1) - assert.Equal(t, outest.BatchSplitRetry, batch.Signals[0].Tag) - }) - - t.Run("drop batch if can't split on entity too large error", func(t *testing.T) { - batch := outest.NewBatch(event1) - - otelConsumer := makeOtelConsumer(t, func(ctx context.Context, ld plog.Logs) error { - return errors.New("Request Entity Too Large") - }) - - err := otelConsumer.Publish(ctx, batch) - assert.NoError(t, err) - assert.Len(t, batch.Signals, 2) - assert.Equal(t, outest.BatchSplitRetry, batch.Signals[0].Tag) - assert.Equal(t, outest.BatchDrop, batch.Signals[1].Tag) - }) - t.Run("drop batch on permanent consumer error", func(t *testing.T) { batch := outest.NewBatch(event1, event2, event3) From 3537486e3be55e89f6115d0bae762b93118116b6 Mon Sep 17 00:00:00 2001 From: David Kilfoyle <41695641+kilfoyle@users.noreply.github.com> Date: Tue, 10 Dec 2024 10:21:55 -0500 Subject: [PATCH 32/48] Add breaking change for Filebeat removed 'docker' input (#41721) --- CHANGELOG.asciidoc | 1 + 1 file changed, 1 insertion(+) diff --git a/CHANGELOG.asciidoc b/CHANGELOG.asciidoc index 21a0639b1e6f..7af434990cfb 100644 --- a/CHANGELOG.asciidoc +++ b/CHANGELOG.asciidoc @@ -2931,6 +2931,7 @@ https://github.com/elastic/beats/compare/v7.17.0\...v8.0.0[View commits] - Add `while_pattern` type to multiline reader. {pull}19662[19662] - auditd dataset: Use `process.args` to store program arguments instead of `auditd.log.aNNN` fields. {pull}29601[29601] - Remove deprecated old `awscloudwatch` input name. {pull}29844[29844] +- Remove `docker` input. Please use `filestream` input with `container` parser or `container` input. {pull}28817[28817] *Metricbeat* From bde07fad474581d1f4507a8229b186b1c7ab8635 Mon Sep 17 00:00:00 2001 From: Maurizio Branca Date: Tue, 10 Dec 2024 18:18:02 +0100 Subject: [PATCH 33/48] Update CODEOWNERS (#41940) Re-assign the component ownership from `elastic/obs-cloud-monitoring` to `elastic/obs-ds-hosted-services`. The practical reason is the old `elastic/obs-cloud-monitoring` team only includes a subset of the current `elastic/obs-ds-hosted-services`. So if the person who approves a PR is not included in `elastic/obs-cloud-monitoring`, I have to ping an additional person. --- .github/CODEOWNERS | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS index 8f060dc48cf3..4b179b381449 100644 --- a/.github/CODEOWNERS +++ b/.github/CODEOWNERS @@ -59,7 +59,7 @@ CHANGELOG* /libbeat/ @elastic/elastic-agent-data-plane /libbeat/docs/processors-list.asciidoc @elastic/ingest-docs /libbeat/management @elastic/elastic-agent-control-plane -/libbeat/processors/add_cloud_metadata @elastic/obs-cloud-monitoring +/libbeat/processors/add_cloud_metadata @elastic/obs-ds-hosted-services /libbeat/processors/add_kubernetes_metadata @elastic/obs-cloudnative-monitoring /libbeat/processors/cache/ @elastic/security-service-integrations /libbeat/processors/community_id/ @elastic/sec-deployment-and-devices @@ -116,10 +116,10 @@ CHANGELOG* /x-pack/filebeat @elastic/elastic-agent-data-plane /x-pack/filebeat/docs/ # Listed without an owner to avoid maintaining doc ownership for each input and module. /x-pack/filebeat/docs/inputs/input-salesforce.asciidoc @elastic/obs-infraobs-integrations -/x-pack/filebeat/input/awscloudwatch/ @elastic/obs-cloud-monitoring -/x-pack/filebeat/input/awss3/ @elastic/obs-cloud-monitoring +/x-pack/filebeat/input/awscloudwatch/ @elastic/obs-ds-hosted-services +/x-pack/filebeat/input/awss3/ @elastic/obs-ds-hosted-services /x-pack/filebeat/input/azureblobstorage/ @elastic/security-service-integrations -/x-pack/filebeat/input/azureeventhub/ @elastic/obs-cloud-monitoring +/x-pack/filebeat/input/azureeventhub/ @elastic/obs-ds-hosted-services /x-pack/filebeat/input/cel/ @elastic/security-service-integrations /x-pack/filebeat/input/cometd/ @elastic/obs-infraobs-integrations /x-pack/filebeat/input/entityanalytics/ @elastic/security-service-integrations @@ -137,9 +137,9 @@ CHANGELOG* /x-pack/filebeat/input/salesforce @elastic/obs-infraobs-integrations /x-pack/filebeat/input/streaming/ @elastic/security-service-integrations /x-pack/filebeat/module/activemq @elastic/obs-infraobs-integrations -/x-pack/filebeat/module/aws @elastic/obs-cloud-monitoring -/x-pack/filebeat/module/awsfargate @elastic/obs-cloud-monitoring -/x-pack/filebeat/module/azure @elastic/obs-cloud-monitoring +/x-pack/filebeat/module/aws @elastic/obs-ds-hosted-services +/x-pack/filebeat/module/awsfargate @elastic/obs-ds-hosted-services +/x-pack/filebeat/module/azure @elastic/obs-ds-hosted-services /x-pack/filebeat/module/barracuda @elastic/security-service-integrations /x-pack/filebeat/module/bluecoat @elastic/sec-deployment-and-devices /x-pack/filebeat/module/cef @elastic/sec-deployment-and-devices From 296b83b6c5c1168b6b09ec3bfca7f4d440628834 Mon Sep 17 00:00:00 2001 From: kruskall <99559985+kruskall@users.noreply.github.com> Date: Tue, 10 Dec 2024 23:08:20 +0100 Subject: [PATCH 34/48] feat: replace custom atomic with sync/atomic (#40132) * feat: replace custom atomic with sync/atomic Go 1.19 added new atomic types. Replace custom atomic types with stdlib atomic package to fully use the race detector, improved lsp hints and support. Use pointers in sniffer struct to prevent copying the atomic struct and cause a race condition. * lint: time.Now().Sub -> time.Since fix golangci-lint issue * Apply suggestions from code review Co-authored-by: Dan Kortschak * refactor: keep Swap usage as is * lint: avoid unnecessary conversion fix golangci-lint issue * fix: update method reference to new atomic types * fix: resolve more compile errors and test failures * lint: fix linter issues * lint: fix linter issues * lint: fix linter issues * lint: fix linter issues * lint: more linting errors * lint: fix linter issues * lint: remove unused import * lint: fix linter issue * lint: fix linter issues * lint: fix linter issues --------- Co-authored-by: Dan Kortschak --- filebeat/channel/outlet.go | 8 +- .../internal/input-logfile/harvester_test.go | 4 +- .../internal/input-logfile/store.go | 8 +- filebeat/input/kafka/input.go | 7 +- filebeat/input/log/input.go | 14 +- filebeat/input/v2/input-cursor/store.go | 10 +- .../v2/input-stateless/stateless_test.go | 14 +- .../inputsource/common/streaming/listener.go | 8 +- heartbeat/monitors/factory_test.go | 8 +- heartbeat/monitors/mocks.go | 14 +- heartbeat/monitors/monitor_test.go | 8 +- heartbeat/scheduler/schedjob.go | 11 +- heartbeat/scheduler/schedjob_test.go | 12 +- libbeat/common/acker/acker.go | 8 +- libbeat/common/atomic/atomic.go | 94 ------ libbeat/common/atomic/atomic32.go | 50 ---- libbeat/common/atomic/atomic64.go | 50 ---- libbeat/common/atomic/atomic_test.go | 273 ------------------ libbeat/idxmgmt/index_support.go | 4 +- libbeat/management/agent.go | 8 +- .../elasticsearch/client_proxy_test.go | 18 +- libbeat/outputs/logstash/async.go | 8 +- .../add_process_metadata.go | 4 +- libbeat/processors/cache/cache.go | 4 +- libbeat/processors/dns/dns.go | 6 +- libbeat/processors/ratelimit/rate_limit.go | 6 +- libbeat/processors/ratelimit/token_bucket.go | 17 +- libbeat/processors/syslog/syslog.go | 6 +- libbeat/publisher/pipeline/client.go | 9 +- .../publisher/pipeline/client_worker_test.go | 32 +- libbeat/publisher/pipeline/controller_test.go | 15 +- libbeat/publisher/pipeline/pipeline.go | 3 +- libbeat/publisher/pipeline/pipeline_test.go | 10 +- libbeat/publisher/pipeline/stress/gen.go | 8 +- libbeat/publisher/pipeline/stress/sig.go | 11 +- libbeat/publisher/testing/connector.go | 17 +- libbeat/tests/integration/framework.go | 5 +- metricbeat/mb/module/runner_group_test.go | 25 +- packetbeat/sniffer/sniffer.go | 9 +- winlogbeat/beater/acker.go | 12 +- winlogbeat/sys/wineventlog/renderer_test.go | 10 +- x-pack/filebeat/input/awss3/metrics_test.go | 2 +- .../internal/kvstore/tracker.go | 8 +- .../internal/kvstore/tracker_test.go | 12 +- .../internal/kvstore/transaction.go | 7 +- .../filebeat/input/gcppubsub/pubsub_test.go | 9 +- .../input/netflow/decoder/atomic/bool.go | 30 -- .../input/netflow/decoder/v9/session.go | 6 +- .../browser/synthexec/execmultiplexer.go | 12 +- x-pack/metricbeat/module/cloudfoundry/v1.go | 6 +- 50 files changed, 223 insertions(+), 717 deletions(-) delete mode 100644 libbeat/common/atomic/atomic.go delete mode 100644 libbeat/common/atomic/atomic32.go delete mode 100644 libbeat/common/atomic/atomic64.go delete mode 100644 libbeat/common/atomic/atomic_test.go delete mode 100644 x-pack/filebeat/input/netflow/decoder/atomic/bool.go diff --git a/filebeat/channel/outlet.go b/filebeat/channel/outlet.go index fd5c9b12fc15..257470463961 100644 --- a/filebeat/channel/outlet.go +++ b/filebeat/channel/outlet.go @@ -18,8 +18,9 @@ package channel import ( + "sync/atomic" + "github.com/elastic/beats/v7/libbeat/beat" - "github.com/elastic/beats/v7/libbeat/common/atomic" ) type outlet struct { @@ -31,15 +32,14 @@ type outlet struct { func newOutlet(client beat.Client) *outlet { o := &outlet{ client: client, - isOpen: atomic.MakeBool(true), done: make(chan struct{}), } + o.isOpen.Store(true) return o } func (o *outlet) Close() error { - isOpen := o.isOpen.Swap(false) - if isOpen { + if o.isOpen.Swap(false) { close(o.done) return o.client.Close() } diff --git a/filebeat/input/filestream/internal/input-logfile/harvester_test.go b/filebeat/input/filestream/internal/input-logfile/harvester_test.go index d8800c85996d..6f5938e308a0 100644 --- a/filebeat/input/filestream/internal/input-logfile/harvester_test.go +++ b/filebeat/input/filestream/internal/input-logfile/harvester_test.go @@ -23,6 +23,7 @@ import ( "fmt" "strings" "sync" + "sync/atomic" "testing" "time" @@ -32,7 +33,6 @@ import ( "github.com/elastic/beats/v7/filebeat/input/filestream/internal/task" input "github.com/elastic/beats/v7/filebeat/input/v2" "github.com/elastic/beats/v7/libbeat/beat" - "github.com/elastic/beats/v7/libbeat/common/atomic" "github.com/elastic/beats/v7/libbeat/tests/resources" "github.com/elastic/elastic-agent-libs/logp" ) @@ -128,7 +128,7 @@ func TestDefaultHarvesterGroup(t *testing.T) { t.Run("assert a harvester is only started if harvester limit haven't been reached", func(t *testing.T) { var wg sync.WaitGroup - var harvesterRunningCount atomic.Int + var harvesterRunningCount atomic.Int64 var harvester1Finished, harvester2Finished atomic.Bool done1, done2 := make(chan struct{}), make(chan struct{}) diff --git a/filebeat/input/filestream/internal/input-logfile/store.go b/filebeat/input/filestream/internal/input-logfile/store.go index 024ca5c9bfdd..14c7869d0877 100644 --- a/filebeat/input/filestream/internal/input-logfile/store.go +++ b/filebeat/input/filestream/internal/input-logfile/store.go @@ -21,9 +21,9 @@ import ( "fmt" "strings" "sync" + "sync/atomic" "time" - "github.com/elastic/beats/v7/libbeat/common/atomic" "github.com/elastic/beats/v7/libbeat/common/cleanup" "github.com/elastic/beats/v7/libbeat/common/transform/typeconv" "github.com/elastic/beats/v7/libbeat/statestore" @@ -461,14 +461,14 @@ func (r *resource) isDeleted() bool { // Retain is used to indicate that 'resource' gets an additional 'owner'. // Owners of an resource can be active inputs or pending update operations // not yet written to disk. -func (r *resource) Retain() { r.pending.Inc() } +func (r *resource) Retain() { r.pending.Add(1) } // Release reduced the owner ship counter of the resource. -func (r *resource) Release() { r.pending.Dec() } +func (r *resource) Release() { r.pending.Add(^uint64(0)) } // UpdatesReleaseN is used to release ownership of N pending update operations. func (r *resource) UpdatesReleaseN(n uint) { - r.pending.Sub(uint64(n)) + r.pending.Add(^uint64(n - 1)) } // Finished returns true if the resource is not in use and if there are no pending updates diff --git a/filebeat/input/kafka/input.go b/filebeat/input/kafka/input.go index 6cc74514befb..3f330587f826 100644 --- a/filebeat/input/kafka/input.go +++ b/filebeat/input/kafka/input.go @@ -25,9 +25,9 @@ import ( "io" "strings" "sync" + "sync/atomic" "time" - "github.com/elastic/beats/v7/libbeat/common/atomic" "github.com/elastic/elastic-agent-libs/mapstr" input "github.com/elastic/beats/v7/filebeat/input/v2" @@ -391,9 +391,10 @@ func (l *listFromFieldReader) Next() (reader.Message, error) { timestamp, kafkaFields := composeEventMetadata(l.claim, l.groupHandler, msg) messages := l.parseMultipleMessages(msg.Value) - neededAcks := atomic.MakeInt(len(messages)) + neededAcks := atomic.Int64{} + neededAcks.Add(int64(len(messages))) ackHandler := func() { - if neededAcks.Dec() == 0 { + if neededAcks.Add(-1) == 0 { l.groupHandler.ack(msg) } } diff --git a/filebeat/input/log/input.go b/filebeat/input/log/input.go index ad93632b372c..e2090f6ebb88 100644 --- a/filebeat/input/log/input.go +++ b/filebeat/input/log/input.go @@ -25,6 +25,7 @@ import ( "sort" "strings" "sync" + "sync/atomic" "time" "github.com/gofrs/uuid/v5" @@ -35,7 +36,6 @@ import ( "github.com/elastic/beats/v7/filebeat/input/file" "github.com/elastic/beats/v7/libbeat/beat" "github.com/elastic/beats/v7/libbeat/common" - "github.com/elastic/beats/v7/libbeat/common/atomic" "github.com/elastic/beats/v7/libbeat/common/cfgwarn" "github.com/elastic/beats/v7/libbeat/management/status" conf "github.com/elastic/elastic-agent-libs/config" @@ -737,8 +737,8 @@ func (p *Input) createHarvester(logger *logp.Logger, state file.State, onTermina // startHarvester starts a new harvester with the given offset // In case the HarvesterLimit is reached, an error is returned func (p *Input) startHarvester(logger *logp.Logger, state file.State, offset int64) error { - if p.numHarvesters.Inc() > p.config.HarvesterLimit && p.config.HarvesterLimit > 0 { - p.numHarvesters.Dec() + if p.numHarvesters.Add(1) > p.config.HarvesterLimit && p.config.HarvesterLimit > 0 { + p.numHarvesters.Add(^uint32(0)) harvesterSkipped.Add(1) return errHarvesterLimit } @@ -747,15 +747,15 @@ func (p *Input) startHarvester(logger *logp.Logger, state file.State, offset int state.Offset = offset // Create harvester with state - h, err := p.createHarvester(logger, state, func() { p.numHarvesters.Dec() }) + h, err := p.createHarvester(logger, state, func() { p.numHarvesters.Add(^uint32(0)) }) if err != nil { - p.numHarvesters.Dec() + p.numHarvesters.Add(^uint32(0)) return err } err = h.Setup() if err != nil { - p.numHarvesters.Dec() + p.numHarvesters.Add(^uint32(0)) return fmt.Errorf("error setting up harvester: %w", err) } @@ -765,7 +765,7 @@ func (p *Input) startHarvester(logger *logp.Logger, state file.State, offset int h.SendStateUpdate() if err = p.harvesters.Start(h); err != nil { - p.numHarvesters.Dec() + p.numHarvesters.Add(^uint32(0)) } return err } diff --git a/filebeat/input/v2/input-cursor/store.go b/filebeat/input/v2/input-cursor/store.go index cc755f046cac..a53bc77a79f9 100644 --- a/filebeat/input/v2/input-cursor/store.go +++ b/filebeat/input/v2/input-cursor/store.go @@ -20,9 +20,9 @@ package cursor import ( "strings" "sync" + "sync/atomic" "time" - "github.com/elastic/beats/v7/libbeat/common/atomic" "github.com/elastic/beats/v7/libbeat/common/cleanup" "github.com/elastic/beats/v7/libbeat/common/transform/typeconv" "github.com/elastic/beats/v7/libbeat/statestore" @@ -235,14 +235,14 @@ func (r *resource) IsNew() bool { // Retain is used to indicate that 'resource' gets an additional 'owner'. // Owners of an resource can be active inputs or pending update operations // not yet written to disk. -func (r *resource) Retain() { r.pending.Inc() } +func (r *resource) Retain() { r.pending.Add(1) } // Release reduced the owner ship counter of the resource. -func (r *resource) Release() { r.pending.Dec() } +func (r *resource) Release() { r.pending.Add(^uint64(0)) } // UpdatesReleaseN is used to release ownership of N pending update operations. func (r *resource) UpdatesReleaseN(n uint) { - r.pending.Sub(uint64(n)) + r.pending.Add(^uint64(n - 1)) } // Finished returns true if the resource is not in use and if there are no pending updates @@ -290,7 +290,7 @@ func readStates(log *logp.Logger, store *statestore.Store, prefix string) (*stat } err := store.Each(func(key string, dec statestore.ValueDecoder) (bool, error) { - if !strings.HasPrefix(string(key), keyPrefix) { + if !strings.HasPrefix(key, keyPrefix) { return true, nil } diff --git a/filebeat/input/v2/input-stateless/stateless_test.go b/filebeat/input/v2/input-stateless/stateless_test.go index 2febcb7e1b6d..731577e76c34 100644 --- a/filebeat/input/v2/input-stateless/stateless_test.go +++ b/filebeat/input/v2/input-stateless/stateless_test.go @@ -22,6 +22,7 @@ import ( "errors" "runtime" "sync" + "sync/atomic" "testing" "github.com/stretchr/testify/require" @@ -29,7 +30,6 @@ import ( v2 "github.com/elastic/beats/v7/filebeat/input/v2" stateless "github.com/elastic/beats/v7/filebeat/input/v2/input-stateless" "github.com/elastic/beats/v7/libbeat/beat" - "github.com/elastic/beats/v7/libbeat/common/atomic" pubtest "github.com/elastic/beats/v7/libbeat/publisher/testing" conf "github.com/elastic/elastic-agent-libs/config" "github.com/elastic/elastic-agent-libs/mapstr" @@ -111,12 +111,12 @@ func TestStateless_Run(t *testing.T) { defer cancel() // connector creates a client the blocks forever until the shutdown signal is received - var publishCalls atomic.Int + var publishCalls atomic.Int64 connector := pubtest.FakeConnector{ ConnectFunc: func(config beat.ClientConfig) (beat.Client, error) { return &pubtest.FakeClient{ PublishFunc: func(event beat.Event) { - publishCalls.Inc() + publishCalls.Add(1) // Unlock Publish once the input has been cancelled <-ctx.Done() }, @@ -141,24 +141,24 @@ func TestStateless_Run(t *testing.T) { // validate require.Equal(t, context.Canceled, err) - require.Equal(t, 1, publishCalls.Load()) + require.Equal(t, int64(1), publishCalls.Load()) }) t.Run("do not start input of pipeline connection fails", func(t *testing.T) { errOpps := errors.New("oops") connector := pubtest.FailingConnector(errOpps) - var run atomic.Int + var run atomic.Int64 input := createConfiguredInput(t, constInputManager(&fakeStatelessInput{ OnRun: func(_ v2.Context, publisher stateless.Publisher) error { - run.Inc() + run.Add(1) return nil }, }), nil) err := input.Run(v2.Context{}, connector) require.True(t, errors.Is(err, errOpps)) - require.Equal(t, 0, run.Load()) + require.Equal(t, int64(0), run.Load()) }) } diff --git a/filebeat/inputsource/common/streaming/listener.go b/filebeat/inputsource/common/streaming/listener.go index ce0f69d030e6..5816c1fa81c9 100644 --- a/filebeat/inputsource/common/streaming/listener.go +++ b/filebeat/inputsource/common/streaming/listener.go @@ -26,9 +26,9 @@ import ( "net" "strings" "sync" + "sync/atomic" "github.com/elastic/beats/v7/filebeat/inputsource" - "github.com/elastic/beats/v7/libbeat/common/atomic" "github.com/elastic/elastic-agent-libs/logp" "github.com/elastic/go-concert/ctxtool" ) @@ -44,7 +44,7 @@ type Listener struct { wg sync.WaitGroup log *logp.Logger ctx ctxtool.CancelContext - clientsCount atomic.Int + clientsCount atomic.Int64 handlerFactory HandlerFactory listenerFactory ListenerFactory } @@ -190,10 +190,10 @@ func (l *Listener) handleConnection(conn net.Conn) { defer cancel() // Track number of clients. - l.clientsCount.Inc() + l.clientsCount.Add(1) log.Debugw("New client connection", "active_clients", l.clientsCount.Load()) defer func() { - l.clientsCount.Dec() + l.clientsCount.Add(-1) log.Debugw("Client disconnected", "active_clients", l.clientsCount.Load()) }() diff --git a/heartbeat/monitors/factory_test.go b/heartbeat/monitors/factory_test.go index e32ac671c8eb..72db7cdf7312 100644 --- a/heartbeat/monitors/factory_test.go +++ b/heartbeat/monitors/factory_test.go @@ -236,8 +236,8 @@ func TestDisabledMonitor(t *testing.T) { require.NoError(t, err) require.IsType(t, NoopRunner{}, runner) - require.Equal(t, 0, built.Load()) - require.Equal(t, 0, closed.Load()) + require.Equal(t, int64(0), built.Load()) + require.Equal(t, int64(0), closed.Load()) } } @@ -353,7 +353,7 @@ func TestDuplicateMonitorIDs(t *testing.T) { // Two are counted as built. The bad config is missing a stdfield so it // doesn't complete construction - require.Equal(t, 2, built.Load()) + require.Equal(t, int64(2), built.Load()) // Only 2 closes, because the bad config isn't closed - require.Equal(t, 2, closed.Load()) + require.Equal(t, int64(2), closed.Load()) } diff --git a/heartbeat/monitors/mocks.go b/heartbeat/monitors/mocks.go index 77dee19858a7..2c4e5e9d0b51 100644 --- a/heartbeat/monitors/mocks.go +++ b/heartbeat/monitors/mocks.go @@ -21,6 +21,7 @@ import ( "fmt" "regexp" "sync" + "sync/atomic" "testing" "time" @@ -42,7 +43,6 @@ import ( "github.com/elastic/beats/v7/heartbeat/monitors/wrappers/monitorstate" "github.com/elastic/beats/v7/heartbeat/scheduler" "github.com/elastic/beats/v7/libbeat/beat" - "github.com/elastic/beats/v7/libbeat/common/atomic" beatversion "github.com/elastic/beats/v7/libbeat/version" ) @@ -212,17 +212,17 @@ func createMockJob() []jobs.Job { return []jobs.Job{j} } -func mockPluginBuilder() (plugin.PluginFactory, *atomic.Int, *atomic.Int) { +func mockPluginBuilder() (plugin.PluginFactory, *atomic.Int64, *atomic.Int64) { reg := monitoring.NewRegistry() - built := atomic.NewInt(0) - closed := atomic.NewInt(0) + built := &atomic.Int64{} + closed := &atomic.Int64{} return plugin.PluginFactory{ Name: "test", Aliases: []string{"testAlias"}, Make: func(s string, config *config.C) (plugin.Plugin, error) { - built.Inc() + built.Add(1) // Declare a real config block with a required attr so we can see what happens when it doesn't work unpacked := struct { URLs []string `config:"urls" validate:"required"` @@ -230,7 +230,7 @@ func mockPluginBuilder() (plugin.PluginFactory, *atomic.Int, *atomic.Int) { // track all closes, even on error closer := func() error { - closed.Inc() + closed.Add(1) return nil } @@ -248,7 +248,7 @@ func mockPluginBuilder() (plugin.PluginFactory, *atomic.Int, *atomic.Int) { closed } -func mockPluginsReg() (p *plugin.PluginsReg, built *atomic.Int, closed *atomic.Int) { +func mockPluginsReg() (p *plugin.PluginsReg, built *atomic.Int64, closed *atomic.Int64) { reg := plugin.NewPluginsReg() builder, built, closed := mockPluginBuilder() _ = reg.Add(builder) diff --git a/heartbeat/monitors/monitor_test.go b/heartbeat/monitors/monitor_test.go index 0890a1697bec..7bb3b5d3fae6 100644 --- a/heartbeat/monitors/monitor_test.go +++ b/heartbeat/monitors/monitor_test.go @@ -106,10 +106,10 @@ func testMonitorConfig(t *testing.T, conf *conf.C, eventValidator validator.Vali t.Fatalf("No publishes detected!") } - assert.Equal(t, 1, built.Load()) + assert.Equal(t, int64(1), built.Load()) mon.Stop() - assert.Equal(t, 1, closed.Load()) + assert.Equal(t, int64(1), closed.Load()) assert.Equal(t, true, pcClient.closed) } @@ -129,8 +129,8 @@ func TestCheckInvalidConfig(t *testing.T) { require.Nil(t, m, "For this test to work we need a nil value for the monitor.") // These counters are both zero since this fails at config parse time - require.Equal(t, 0, built.Load()) - require.Equal(t, 0, closed.Load()) + require.Equal(t, int64(0), built.Load()) + require.Equal(t, int64(0), closed.Load()) require.Error(t, checkMonitorConfig(serverMonConf, reg)) } diff --git a/heartbeat/scheduler/schedjob.go b/heartbeat/scheduler/schedjob.go index 2a8172b95641..50f94a895d0b 100644 --- a/heartbeat/scheduler/schedjob.go +++ b/heartbeat/scheduler/schedjob.go @@ -20,11 +20,11 @@ package scheduler import ( "context" "sync" + "sync/atomic" "time" "golang.org/x/sync/semaphore" - "github.com/elastic/beats/v7/libbeat/common/atomic" "github.com/elastic/elastic-agent-libs/logp" ) @@ -35,7 +35,7 @@ type schedJob struct { wg *sync.WaitGroup entrypoint TaskFunc jobLimitSem *semaphore.Weighted - activeTasks atomic.Int + activeTasks atomic.Int64 } // runRecursiveJob runs the entry point for a job, blocking until all subtasks are completed. @@ -48,7 +48,6 @@ func newSchedJob(ctx context.Context, s *Scheduler, id string, jobType string, t scheduler: s, jobLimitSem: s.jobLimitSem[jobType], entrypoint: task, - activeTasks: atomic.MakeInt(0), wg: &sync.WaitGroup{}, } } @@ -59,7 +58,7 @@ func newSchedJob(ctx context.Context, s *Scheduler, id string, jobType string, t // The wait group passed into this function expects to already have its count incremented by one. func (sj *schedJob) run() (startedAt time.Time) { sj.wg.Add(1) - sj.activeTasks.Inc() + sj.activeTasks.Add(1) if sj.jobLimitSem != nil { err := sj.jobLimitSem.Acquire(sj.ctx, 1) // Defer release only if acquired @@ -82,7 +81,7 @@ func (sj *schedJob) run() (startedAt time.Time) { // The wait group passed into this function expects to already have its count incremented by one. func (sj *schedJob) runTask(task TaskFunc) time.Time { defer sj.wg.Done() - defer sj.activeTasks.Dec() + defer sj.activeTasks.Add(-1) // The accounting for waiting/active tasks is done using atomics. // Absolute accuracy is not critical here so the gap between modifying waitingTasks and activeJobs is acceptable. @@ -113,7 +112,7 @@ func (sj *schedJob) runTask(task TaskFunc) time.Time { sj.scheduler.stats.activeTasks.Dec() sj.wg.Add(len(continuations)) - sj.activeTasks.Add(len(continuations)) + sj.activeTasks.Add(int64(len(continuations))) for _, cont := range continuations { // Run continuations in parallel, note that these each will acquire their own slots // We can discard the started at times for continuations as those are diff --git a/heartbeat/scheduler/schedjob_test.go b/heartbeat/scheduler/schedjob_test.go index 24e6178e1622..f989014f467c 100644 --- a/heartbeat/scheduler/schedjob_test.go +++ b/heartbeat/scheduler/schedjob_test.go @@ -20,13 +20,13 @@ package scheduler import ( "context" "sync" + "sync/atomic" "testing" "time" "github.com/stretchr/testify/require" "github.com/elastic/beats/v7/heartbeat/config" - batomic "github.com/elastic/beats/v7/libbeat/common/atomic" "github.com/elastic/elastic-agent-libs/monitoring" ) @@ -72,7 +72,7 @@ func TestSchedJobRun(t *testing.T) { wg := &sync.WaitGroup{} wg.Add(1) - executed := batomic.MakeBool(false) + executed := &atomic.Bool{} tf := func(ctx context.Context) []TaskFunc { executed.Store(true) @@ -102,14 +102,14 @@ func TestRecursiveForkingJob(t *testing.T) { s := Create(1000, monitoring.NewRegistry(), tarawaTime(), map[string]*config.JobLimit{ "atype": {Limit: 1}, }, false) - ran := batomic.NewInt(0) + var ran atomic.Int64 var terminalTf TaskFunc = func(ctx context.Context) []TaskFunc { - ran.Inc() + ran.Add(1) return nil } var forkingTf TaskFunc = func(ctx context.Context) []TaskFunc { - ran.Inc() + ran.Add(1) return []TaskFunc{ terminalTf, terminalTf, terminalTf, } @@ -118,6 +118,6 @@ func TestRecursiveForkingJob(t *testing.T) { sj := newSchedJob(context.Background(), s, "myid", "atype", forkingTf) sj.run() - require.Equal(t, 4, ran.Load()) + require.Equal(t, int64(4), ran.Load()) } diff --git a/libbeat/common/acker/acker.go b/libbeat/common/acker/acker.go index c75aec13564b..47c019a576f1 100644 --- a/libbeat/common/acker/acker.go +++ b/libbeat/common/acker/acker.go @@ -19,9 +19,9 @@ package acker import ( "sync" + "sync/atomic" "github.com/elastic/beats/v7/libbeat/beat" - "github.com/elastic/beats/v7/libbeat/common/atomic" ) // Nil creates an ACKer that does nothing. @@ -98,7 +98,7 @@ type gapInfo struct { } func (a *trackingACKer) AddEvent(_ beat.Event, published bool) { - a.events.Inc() + a.events.Add(1) if published { a.addPublishedEvent() } else { @@ -148,7 +148,7 @@ func (a *trackingACKer) addDropEvent() { a.lst.Unlock() current.Unlock() - a.events.Dec() + a.events.Add(^uint32(0)) return } @@ -202,7 +202,7 @@ func (a *trackingACKer) ACKEvents(n int) { current.Unlock() } - a.events.Sub(uint32(total)) + a.events.Add(^uint32(total - 1)) a.fn(acked, total) } diff --git a/libbeat/common/atomic/atomic.go b/libbeat/common/atomic/atomic.go deleted file mode 100644 index 09e83614184f..000000000000 --- a/libbeat/common/atomic/atomic.go +++ /dev/null @@ -1,94 +0,0 @@ -// Licensed to Elasticsearch B.V. under one or more contributor -// license agreements. See the NOTICE file distributed with -// this work for additional information regarding copyright -// ownership. Elasticsearch B.V. licenses this file to you under -// the Apache License, Version 2.0 (the "License"); you may -// not use this file except in compliance with the License. -// You may obtain a copy of the License at -// -// http://www.apache.org/licenses/LICENSE-2.0 -// -// Unless required by applicable law or agreed to in writing, -// software distributed under the License is distributed on an -// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY -// KIND, either express or implied. See the License for the -// specific language governing permissions and limitations -// under the License. - -// Package atomic provides common primitive types with atomic accessors. -package atomic - -import a "sync/atomic" - -// Bool provides an atomic boolean type. -type Bool struct{ u Uint32 } - -// Int32 provides an atomic int32 type. -type Int32 struct{ value int32 } - -// Int64 provides an atomic int64 type. -type Int64 struct{ value int64 } - -// Uint32 provides an atomic uint32 type. -type Uint32 struct{ value uint32 } - -// Uint64 provides an atomic uint64 type. -type Uint64 struct{ value uint64 } - -func MakeBool(v bool) Bool { return Bool{MakeUint32(encBool(v))} } -func NewBool(v bool) *Bool { return &Bool{MakeUint32(encBool(v))} } -func (b *Bool) Load() bool { return b.u.Load() == 1 } -func (b *Bool) Store(v bool) { b.u.Store(encBool(v)) } -func (b *Bool) Swap(new bool) bool { return b.u.Swap(encBool(new)) == 1 } -func (b *Bool) CAS(old, new bool) bool { return b.u.CAS(encBool(old), encBool(new)) } - -func MakeInt32(v int32) Int32 { return Int32{v} } -func NewInt32(v int32) *Int32 { return &Int32{v} } -func (i *Int32) Load() int32 { return a.LoadInt32(&i.value) } -func (i *Int32) Store(v int32) { a.StoreInt32(&i.value, v) } -func (i *Int32) Swap(new int32) int32 { return a.SwapInt32(&i.value, new) } -func (i *Int32) Add(delta int32) int32 { return a.AddInt32(&i.value, delta) } -func (i *Int32) Sub(delta int32) int32 { return a.AddInt32(&i.value, -delta) } -func (i *Int32) Inc() int32 { return i.Add(1) } -func (i *Int32) Dec() int32 { return i.Add(-1) } -func (i *Int32) CAS(old, new int32) bool { return a.CompareAndSwapInt32(&i.value, old, new) } - -func MakeInt64(v int64) Int64 { return Int64{v} } -func NewInt64(v int64) *Int64 { return &Int64{v} } -func (i *Int64) Load() int64 { return a.LoadInt64(&i.value) } -func (i *Int64) Store(v int64) { a.StoreInt64(&i.value, v) } -func (i *Int64) Swap(new int64) int64 { return a.SwapInt64(&i.value, new) } -func (i *Int64) Add(delta int64) int64 { return a.AddInt64(&i.value, delta) } -func (i *Int64) Sub(delta int64) int64 { return a.AddInt64(&i.value, -delta) } -func (i *Int64) Inc() int64 { return i.Add(1) } -func (i *Int64) Dec() int64 { return i.Add(-1) } -func (i *Int64) CAS(old, new int64) bool { return a.CompareAndSwapInt64(&i.value, old, new) } - -func MakeUint32(v uint32) Uint32 { return Uint32{v} } -func NewUint32(v uint32) *Uint32 { return &Uint32{v} } -func (u *Uint32) Load() uint32 { return a.LoadUint32(&u.value) } -func (u *Uint32) Store(v uint32) { a.StoreUint32(&u.value, v) } -func (u *Uint32) Swap(new uint32) uint32 { return a.SwapUint32(&u.value, new) } -func (u *Uint32) Add(delta uint32) uint32 { return a.AddUint32(&u.value, delta) } -func (u *Uint32) Sub(delta uint32) uint32 { return a.AddUint32(&u.value, ^uint32(delta-1)) } -func (u *Uint32) Inc() uint32 { return u.Add(1) } -func (u *Uint32) Dec() uint32 { return u.Add(^uint32(0)) } -func (u *Uint32) CAS(old, new uint32) bool { return a.CompareAndSwapUint32(&u.value, old, new) } - -func MakeUint64(v uint64) Uint64 { return Uint64{v} } -func NewUint64(v uint64) *Uint64 { return &Uint64{v} } -func (u *Uint64) Load() uint64 { return a.LoadUint64(&u.value) } -func (u *Uint64) Store(v uint64) { a.StoreUint64(&u.value, v) } -func (u *Uint64) Swap(new uint64) uint64 { return a.SwapUint64(&u.value, new) } -func (u *Uint64) Add(delta uint64) uint64 { return a.AddUint64(&u.value, delta) } -func (u *Uint64) Sub(delta uint64) uint64 { return a.AddUint64(&u.value, ^uint64(delta-1)) } -func (u *Uint64) Inc() uint64 { return u.Add(1) } -func (u *Uint64) Dec() uint64 { return u.Add(^uint64(0)) } -func (u *Uint64) CAS(old, new uint64) bool { return a.CompareAndSwapUint64(&u.value, old, new) } - -func encBool(b bool) uint32 { - if b { - return 1 - } - return 0 -} diff --git a/libbeat/common/atomic/atomic32.go b/libbeat/common/atomic/atomic32.go deleted file mode 100644 index d811070a6cd7..000000000000 --- a/libbeat/common/atomic/atomic32.go +++ /dev/null @@ -1,50 +0,0 @@ -// Licensed to Elasticsearch B.V. under one or more contributor -// license agreements. See the NOTICE file distributed with -// this work for additional information regarding copyright -// ownership. Elasticsearch B.V. licenses this file to you under -// the Apache License, Version 2.0 (the "License"); you may -// not use this file except in compliance with the License. -// You may obtain a copy of the License at -// -// http://www.apache.org/licenses/LICENSE-2.0 -// -// Unless required by applicable law or agreed to in writing, -// software distributed under the License is distributed on an -// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY -// KIND, either express or implied. See the License for the -// specific language governing permissions and limitations -// under the License. - -//go:build 386 || arm || mips || mipsle - -package atomic - -// atomic Uint/Int for 32bit systems - -// Uint provides an architecture specific atomic uint. -type Uint struct{ a Uint32 } - -// Int provides an architecture specific atomic uint. -type Int struct{ a Int32 } - -func MakeUint(v uint) Uint { return Uint{MakeUint32(uint32(v))} } -func NewUint(v uint) *Uint { return &Uint{MakeUint32(uint32(v))} } -func (u *Uint) Load() uint { return uint(u.a.Load()) } -func (u *Uint) Store(v uint) { u.a.Store(uint32(v)) } -func (u *Uint) Swap(new uint) uint { return uint(u.a.Swap(uint32(new))) } -func (u *Uint) Add(delta uint) uint { return uint(u.a.Add(uint32(delta))) } -func (u *Uint) Sub(delta uint) uint { return uint(u.a.Add(uint32(-delta))) } -func (u *Uint) Inc() uint { return uint(u.a.Inc()) } -func (u *Uint) Dec() uint { return uint(u.a.Dec()) } -func (u *Uint) CAS(old, new uint) bool { return u.a.CAS(uint32(old), uint32(new)) } - -func MakeInt(v int) Int { return Int{MakeInt32(int32(v))} } -func NewInt(v int) *Int { return &Int{MakeInt32(int32(v))} } -func (i *Int) Load() int { return int(i.a.Load()) } -func (i *Int) Store(v int) { i.a.Store(int32(v)) } -func (i *Int) Swap(new int) int { return int(i.a.Swap(int32(new))) } -func (i *Int) Add(delta int) int { return int(i.a.Add(int32(delta))) } -func (i *Int) Sub(delta int) int { return int(i.a.Add(int32(-delta))) } -func (i *Int) Inc() int { return int(i.a.Inc()) } -func (i *Int) Dec() int { return int(i.a.Dec()) } -func (i *Int) CAS(old, new int) bool { return i.a.CAS(int32(old), int32(new)) } diff --git a/libbeat/common/atomic/atomic64.go b/libbeat/common/atomic/atomic64.go deleted file mode 100644 index 3f3648e91ce1..000000000000 --- a/libbeat/common/atomic/atomic64.go +++ /dev/null @@ -1,50 +0,0 @@ -// Licensed to Elasticsearch B.V. under one or more contributor -// license agreements. See the NOTICE file distributed with -// this work for additional information regarding copyright -// ownership. Elasticsearch B.V. licenses this file to you under -// the Apache License, Version 2.0 (the "License"); you may -// not use this file except in compliance with the License. -// You may obtain a copy of the License at -// -// http://www.apache.org/licenses/LICENSE-2.0 -// -// Unless required by applicable law or agreed to in writing, -// software distributed under the License is distributed on an -// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY -// KIND, either express or implied. See the License for the -// specific language governing permissions and limitations -// under the License. - -//go:build amd64 || arm64 || ppc64 || ppc64le || mips64 || mips64le || s390x - -package atomic - -// atomic Uint/Int for 64bit systems - -// Uint provides an architecture specific atomic uint. -type Uint struct{ a Uint64 } - -// Int provides an architecture specific atomic uint. -type Int struct{ a Int64 } - -func MakeUint(v uint) Uint { return Uint{MakeUint64(uint64(v))} } -func NewUint(v uint) *Uint { return &Uint{MakeUint64(uint64(v))} } -func (u *Uint) Load() uint { return uint(u.a.Load()) } -func (u *Uint) Store(v uint) { u.a.Store(uint64(v)) } -func (u *Uint) Swap(new uint) uint { return uint(u.a.Swap(uint64(new))) } -func (u *Uint) Add(delta uint) uint { return uint(u.a.Add(uint64(delta))) } -func (u *Uint) Sub(delta uint) uint { return uint(u.a.Add(uint64(-delta))) } -func (u *Uint) Inc() uint { return uint(u.a.Inc()) } -func (u *Uint) Dec() uint { return uint(u.a.Dec()) } -func (u *Uint) CAS(old, new uint) bool { return u.a.CAS(uint64(old), uint64(new)) } - -func MakeInt(v int) Int { return Int{MakeInt64(int64(v))} } -func NewInt(v int) *Int { return &Int{MakeInt64(int64(v))} } -func (i *Int) Load() int { return int(i.a.Load()) } -func (i *Int) Store(v int) { i.a.Store(int64(v)) } -func (i *Int) Swap(new int) int { return int(i.a.Swap(int64(new))) } -func (i *Int) Add(delta int) int { return int(i.a.Add(int64(delta))) } -func (i *Int) Sub(delta int) int { return int(i.a.Add(int64(-delta))) } -func (i *Int) Inc() int { return int(i.a.Inc()) } -func (i *Int) Dec() int { return int(i.a.Dec()) } -func (i *Int) CAS(old, new int) bool { return i.a.CAS(int64(old), int64(new)) } diff --git a/libbeat/common/atomic/atomic_test.go b/libbeat/common/atomic/atomic_test.go deleted file mode 100644 index f4df6fc4d89e..000000000000 --- a/libbeat/common/atomic/atomic_test.go +++ /dev/null @@ -1,273 +0,0 @@ -// Licensed to Elasticsearch B.V. under one or more contributor -// license agreements. See the NOTICE file distributed with -// this work for additional information regarding copyright -// ownership. Elasticsearch B.V. licenses this file to you under -// the Apache License, Version 2.0 (the "License"); you may -// not use this file except in compliance with the License. -// You may obtain a copy of the License at -// -// http://www.apache.org/licenses/LICENSE-2.0 -// -// Unless required by applicable law or agreed to in writing, -// software distributed under the License is distributed on an -// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY -// KIND, either express or implied. See the License for the -// specific language governing permissions and limitations -// under the License. - -package atomic - -import ( - "testing" - - "github.com/stretchr/testify/assert" -) - -func TestAtomicBool(t *testing.T) { - assert := assert.New(t) - - var b Bool - assert.False(b.Load(), "check zero value is false") - - b = MakeBool(true) - assert.True(b.Load(), "check value initializer with 'true' value") - - b.Store(false) - assert.False(b.Load(), "check store to false") - - old := b.Swap(true) - assert.False(old, "check old value of swap operation is 'false'") - assert.True(b.Load(), "check new value after swap is 'true'") - - old = b.Swap(false) - assert.True(old, "check old value of second swap operation is 'true'") - assert.False(b.Load(), "check new value after second swap is 'false'") - - ok := b.CAS(true, true) - assert.False(ok, "check CAS fails with wrong 'old' value") - assert.False(b.Load(), "check failed CAS did not change value 'false'") - - ok = b.CAS(false, true) - assert.True(ok, "check CAS succeeds with correct 'old' value") - assert.True(b.Load(), "check CAS did change value to 'true'") -} - -func TestAtomicInt32(t *testing.T) { - assert := assert.New(t) - check := func(expected, actual int32, msg string) { - assert.Equal(expected, actual, msg) - } - - var v Int32 - check(0, v.Load(), "check zero value") - - v = MakeInt32(23) - check(23, v.Load(), "check value initializer") - - v.Store(42) - check(42, v.Load(), "check store new value") - - new := v.Inc() - check(43, new, "check increment returns new value") - check(43, v.Load(), "check increment did store new value") - - new = v.Dec() - check(42, new, "check decrement returns new value") - check(42, v.Load(), "check decrement did store new value") - - new = v.Add(8) - check(50, new, "check add returns new value") - check(50, v.Load(), "check add did store new value") - - new = v.Sub(8) - check(42, new, "check sub returns new value") - check(42, v.Load(), "check sub did store new value") - - old := v.Swap(101) - check(42, old, "check swap returns old value") - check(101, v.Load(), "check swap stores new value") - - ok := v.CAS(0, 23) - assert.False(ok, "check CAS with wrong old value fails") - check(101, v.Load(), "check failed CAS did not change value") - - ok = v.CAS(101, 23) - assert.True(ok, "check CAS succeeds") - check(23, v.Load(), "check CAS did store new value") -} - -func TestAtomicInt64(t *testing.T) { - assert := assert.New(t) - check := func(expected, actual int64, msg string) { - assert.Equal(expected, actual, msg) - } - - var v Int64 - check(0, v.Load(), "check zero value") - - v = MakeInt64(23) - check(23, v.Load(), "check value initializer") - - v.Store(42) - check(42, v.Load(), "check store new value") - - new := v.Inc() - check(43, new, "check increment returns new value") - check(43, v.Load(), "check increment did store new value") - - new = v.Dec() - check(42, new, "check decrement returns new value") - check(42, v.Load(), "check decrement did store new value") - - new = v.Add(8) - check(50, new, "check add returns new value") - check(50, v.Load(), "check add did store new value") - - new = v.Sub(8) - check(42, new, "check sub returns new value") - check(42, v.Load(), "check sub did store new value") - - old := v.Swap(101) - check(42, old, "check swap returns old value") - check(101, v.Load(), "check swap stores new value") - - ok := v.CAS(0, 23) - assert.False(ok, "check CAS with wrong old value fails") - check(101, v.Load(), "check failed CAS did not change value") - - ok = v.CAS(101, 23) - assert.True(ok, "check CAS succeeds") - check(23, v.Load(), "check CAS did store new value") -} - -func TestAtomicUint32(t *testing.T) { - assert := assert.New(t) - check := func(expected, actual uint32, msg string) { - assert.Equal(expected, actual, msg) - } - - var v Uint32 - check(0, v.Load(), "check zero value") - - v = MakeUint32(23) - check(23, v.Load(), "check value initializer") - - v.Store(42) - check(42, v.Load(), "check store new value") - - new := v.Inc() - check(43, new, "check increment returns new value") - check(43, v.Load(), "check increment did store new value") - - new = v.Dec() - check(42, new, "check decrement returns new value") - check(42, v.Load(), "check decrement did store new value") - - new = v.Add(8) - check(50, new, "check add returns new value") - check(50, v.Load(), "check add did store new value") - - new = v.Sub(8) - check(42, new, "check sub returns new value") - check(42, v.Load(), "check sub did store new value") - - old := v.Swap(101) - check(42, old, "check swap returns old value") - check(101, v.Load(), "check swap stores new value") - - ok := v.CAS(0, 23) - assert.False(ok, "check CAS with wrong old value fails") - check(101, v.Load(), "check failed CAS did not change value") - - ok = v.CAS(101, 23) - assert.True(ok, "check CAS succeeds") - check(23, v.Load(), "check CAS did store new value") -} - -func TestAtomicUint64(t *testing.T) { - assert := assert.New(t) - check := func(expected, actual uint64, msg string) { - assert.Equal(expected, actual, msg) - } - - var v Uint64 - check(0, v.Load(), "check zero value") - - v = MakeUint64(23) - check(23, v.Load(), "check value initializer") - - v.Store(42) - check(42, v.Load(), "check store new value") - - new := v.Inc() - check(43, new, "check increment returns new value") - check(43, v.Load(), "check increment did store new value") - - new = v.Dec() - check(42, new, "check decrement returns new value") - check(42, v.Load(), "check decrement did store new value") - - new = v.Add(8) - check(50, new, "check add returns new value") - check(50, v.Load(), "check add did store new value") - - new = v.Sub(8) - check(42, new, "check sub returns new value") - check(42, v.Load(), "check sub did store new value") - - old := v.Swap(101) - check(42, old, "check swap returns old value") - check(101, v.Load(), "check swap stores new value") - - ok := v.CAS(0, 23) - assert.False(ok, "check CAS with wrong old value fails") - check(101, v.Load(), "check failed CAS did not change value") - - ok = v.CAS(101, 23) - assert.True(ok, "check CAS succeeds") - check(23, v.Load(), "check CAS did store new value") -} - -func TestAtomicUint(t *testing.T) { - assert := assert.New(t) - check := func(expected, actual uint, msg string) { - assert.Equal(expected, actual, msg) - } - - var v Uint - check(0, v.Load(), "check zero value") - - v = MakeUint(23) - check(23, v.Load(), "check value initializer") - - v.Store(42) - check(42, v.Load(), "check store new value") - - new := v.Inc() - check(43, new, "check increment returns new value") - check(43, v.Load(), "check increment did store new value") - - new = v.Dec() - check(42, new, "check decrement returns new value") - check(42, v.Load(), "check decrement did store new value") - - new = v.Add(8) - check(50, new, "check add returns new value") - check(50, v.Load(), "check add did store new value") - - new = v.Sub(8) - check(42, new, "check sub returns new value") - check(42, v.Load(), "check sub did store new value") - - old := v.Swap(101) - check(42, old, "check swap returns old value") - check(101, v.Load(), "check swap stores new value") - - ok := v.CAS(0, 23) - assert.False(ok, "check CAS with wrong old value fails") - check(101, v.Load(), "check failed CAS did not change value") - - ok = v.CAS(101, 23) - assert.True(ok, "check CAS succeeds") - check(23, v.Load(), "check CAS did store new value") -} diff --git a/libbeat/idxmgmt/index_support.go b/libbeat/idxmgmt/index_support.go index 4526d916c359..57816b3625c5 100644 --- a/libbeat/idxmgmt/index_support.go +++ b/libbeat/idxmgmt/index_support.go @@ -21,10 +21,10 @@ import ( "errors" "fmt" "strings" + "sync/atomic" "github.com/elastic/beats/v7/libbeat/beat" "github.com/elastic/beats/v7/libbeat/beat/events" - "github.com/elastic/beats/v7/libbeat/common/atomic" "github.com/elastic/beats/v7/libbeat/idxmgmt/lifecycle" "github.com/elastic/beats/v7/libbeat/outputs" "github.com/elastic/beats/v7/libbeat/outputs/outil" @@ -314,7 +314,7 @@ func (m *indexManager) setupWithILM() (bool, error) { } if withILM { // mark ILM as enabled in indexState - m.support.st.withILM.CAS(false, true) + m.support.st.withILM.CompareAndSwap(false, true) } } return withILM, nil diff --git a/libbeat/management/agent.go b/libbeat/management/agent.go index 84f5a1e9f6b1..cd14f8cb9690 100644 --- a/libbeat/management/agent.go +++ b/libbeat/management/agent.go @@ -17,17 +17,15 @@ package management -import ( - "github.com/elastic/beats/v7/libbeat/common/atomic" -) +import "sync/atomic" var ( // underAgent is set to true with this beat is being ran under the elastic-agent - underAgent = atomic.MakeBool(false) + underAgent atomic.Bool // underAgentTrace is set to true when the elastic-agent has placed this beat into // trace mode (which enables logging of published events) - underAgentTrace = atomic.MakeBool(false) + underAgentTrace atomic.Bool ) // SetUnderAgent sets that the processing pipeline is being ran under the elastic-agent. diff --git a/libbeat/outputs/elasticsearch/client_proxy_test.go b/libbeat/outputs/elasticsearch/client_proxy_test.go index bd6739c3bf02..b0cef2824870 100644 --- a/libbeat/outputs/elasticsearch/client_proxy_test.go +++ b/libbeat/outputs/elasticsearch/client_proxy_test.go @@ -29,12 +29,12 @@ import ( "net/url" "os" "os/exec" + "sync/atomic" "testing" "github.com/stretchr/testify/assert" "github.com/stretchr/testify/require" - "github.com/elastic/beats/v7/libbeat/common/atomic" "github.com/elastic/beats/v7/libbeat/esleg/eslegclient" "github.com/elastic/beats/v7/libbeat/outputs/outil" "github.com/elastic/elastic-agent-libs/transport/httpcommon" @@ -224,17 +224,17 @@ type serverState struct { serverURL string proxyURL string - _serverRequestCount atomic.Int // Requests directly to the server - _proxyRequestCount atomic.Int // Requests via the proxy + _serverRequestCount atomic.Int64 // Requests directly to the server + _proxyRequestCount atomic.Int64 // Requests via the proxy } // Convenience functions to unwrap the atomic primitives -func (s serverState) serverRequestCount() int { - return s._serverRequestCount.Load() +func (s *serverState) serverRequestCount() int { + return int(s._serverRequestCount.Load()) } -func (s serverState) proxyRequestCount() int { - return s._proxyRequestCount.Load() +func (s *serverState) proxyRequestCount() int { + return int(s._proxyRequestCount.Load()) } // startServers starts endpoints representing a backend server and a proxy, @@ -246,13 +246,13 @@ func startServers(t *testing.T) (*serverState, func()) { http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { assert.Equal(t, headerTestValue, r.Header.Get(headerTestField)) fmt.Fprintln(w, "Hello, client") - state._serverRequestCount.Inc() + state._serverRequestCount.Add(1) })) proxy := httptest.NewServer( http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { assert.Equal(t, headerTestValue, r.Header.Get(headerTestField)) fmt.Fprintln(w, "Hello, client") - state._proxyRequestCount.Inc() + state._proxyRequestCount.Add(1) })) state.serverURL = server.URL state.proxyURL = proxy.URL diff --git a/libbeat/outputs/logstash/async.go b/libbeat/outputs/logstash/async.go index a980d1cef32c..f0da5e45943d 100644 --- a/libbeat/outputs/logstash/async.go +++ b/libbeat/outputs/logstash/async.go @@ -22,10 +22,10 @@ import ( "errors" "net" "sync" + "sync/atomic" "time" "github.com/elastic/beats/v7/libbeat/beat" - "github.com/elastic/beats/v7/libbeat/common/atomic" "github.com/elastic/beats/v7/libbeat/outputs" "github.com/elastic/beats/v7/libbeat/publisher" "github.com/elastic/elastic-agent-libs/logp" @@ -147,13 +147,13 @@ func (c *asyncClient) Publish(_ context.Context, batch publisher.Batch) error { ref := &msgRef{ client: c, - count: atomic.MakeUint32(1), batch: batch, slice: events, batchSize: len(events), win: c.win, err: nil, } + ref.count.Store(1) defer ref.dec() for len(events) > 0 { @@ -218,7 +218,7 @@ func (c *asyncClient) sendEvents(ref *msgRef, events []publisher.Event) error { for i := range events { window[i] = &events[i].Content } - ref.count.Inc() + ref.count.Add(1) return client.Send(ref.callback, window) } @@ -261,7 +261,7 @@ func (r *msgRef) fail(n uint32, err error) { } func (r *msgRef) dec() { - i := r.count.Dec() + i := r.count.Add(^uint32(0)) if i > 0 { return } diff --git a/libbeat/processors/add_process_metadata/add_process_metadata.go b/libbeat/processors/add_process_metadata/add_process_metadata.go index 2385e5f99def..78e67f8e4d70 100644 --- a/libbeat/processors/add_process_metadata/add_process_metadata.go +++ b/libbeat/processors/add_process_metadata/add_process_metadata.go @@ -22,11 +22,11 @@ import ( "fmt" "reflect" "strconv" + "sync/atomic" "time" "github.com/elastic/beats/v7/libbeat/beat" "github.com/elastic/beats/v7/libbeat/common" - "github.com/elastic/beats/v7/libbeat/common/atomic" "github.com/elastic/beats/v7/libbeat/processors" jsprocessor "github.com/elastic/beats/v7/libbeat/processors/script/javascript/module/processor" conf "github.com/elastic/elastic-agent-libs/config" @@ -131,7 +131,7 @@ func NewWithConfig(opts ...ConfigOption) (beat.Processor, error) { func newProcessMetadataProcessorWithProvider(config config, provider processMetadataProvider, withCache bool) (proc beat.Processor, err error) { // Logging (each processor instance has a unique ID). var ( - id = int(instanceID.Inc()) + id = int(instanceID.Add(1)) log = logp.NewLogger(processorName).With("instance_id", id) ) diff --git a/libbeat/processors/cache/cache.go b/libbeat/processors/cache/cache.go index a7ce4876f505..45c1e41872ef 100644 --- a/libbeat/processors/cache/cache.go +++ b/libbeat/processors/cache/cache.go @@ -22,10 +22,10 @@ import ( "errors" "fmt" "os" + "sync/atomic" "time" "github.com/elastic/beats/v7/libbeat/beat" - "github.com/elastic/beats/v7/libbeat/common/atomic" "github.com/elastic/beats/v7/libbeat/processors" conf "github.com/elastic/elastic-agent-libs/config" "github.com/elastic/elastic-agent-libs/logp" @@ -67,7 +67,7 @@ func New(cfg *conf.C) (beat.Processor, error) { return nil, fmt.Errorf("failed to unpack the %s configuration: %w", name, err) } // Logging (each processor instance has a unique ID). - id := int(instanceID.Inc()) + id := int(instanceID.Add(1)) log := logp.NewLogger(name).With("instance_id", id) src, cancel, err := getStoreFor(config, log) diff --git a/libbeat/processors/dns/dns.go b/libbeat/processors/dns/dns.go index d4f3d2ba57b9..48b08ab671c9 100644 --- a/libbeat/processors/dns/dns.go +++ b/libbeat/processors/dns/dns.go @@ -22,9 +22,9 @@ import ( "strconv" "strings" "sync" + "sync/atomic" "github.com/elastic/beats/v7/libbeat/beat" - "github.com/elastic/beats/v7/libbeat/common/atomic" "github.com/elastic/beats/v7/libbeat/processors" jsprocessor "github.com/elastic/beats/v7/libbeat/processors/script/javascript/module/processor" conf "github.com/elastic/elastic-agent-libs/config" @@ -36,7 +36,7 @@ import ( const logName = "processor.dns" // instanceID is used to assign each instance a unique monitoring namespace. -var instanceID = atomic.MakeUint32(0) +var instanceID atomic.Uint32 func init() { processors.RegisterPlugin("dns", New) @@ -58,7 +58,7 @@ func New(cfg *conf.C) (beat.Processor, error) { // Logging and metrics (each processor instance has a unique ID). var ( - id = int(instanceID.Inc()) + id = int(instanceID.Add(1)) log = logp.NewLogger(logName).With("instance_id", id) metrics = monitoring.Default.NewRegistry(logName+"."+strconv.Itoa(id), monitoring.DoNotReport) ) diff --git a/libbeat/processors/ratelimit/rate_limit.go b/libbeat/processors/ratelimit/rate_limit.go index f558b076e2ba..92d9b4c37a0b 100644 --- a/libbeat/processors/ratelimit/rate_limit.go +++ b/libbeat/processors/ratelimit/rate_limit.go @@ -22,12 +22,12 @@ import ( "fmt" "sort" "strconv" + "sync/atomic" "github.com/jonboulle/clockwork" "github.com/mitchellh/hashstructure" "github.com/elastic/beats/v7/libbeat/beat" - "github.com/elastic/beats/v7/libbeat/common/atomic" "github.com/elastic/beats/v7/libbeat/processors" c "github.com/elastic/elastic-agent-libs/config" "github.com/elastic/elastic-agent-libs/logp" @@ -36,7 +36,7 @@ import ( ) // instanceID is used to assign each instance a unique monitoring namespace. -var instanceID = atomic.MakeUint32(0) +var instanceID atomic.Uint32 const processorName = "rate_limit" const logName = "processor." + processorName @@ -79,7 +79,7 @@ func new(cfg *c.C) (beat.Processor, error) { // Logging and metrics (each processor instance has a unique ID). var ( - id = int(instanceID.Inc()) + id = int(instanceID.Add(1)) log = logp.NewLogger(logName).With("instance_id", id) reg = monitoring.Default.NewRegistry(logName+"."+strconv.Itoa(id), monitoring.DoNotReport) ) diff --git a/libbeat/processors/ratelimit/token_bucket.go b/libbeat/processors/ratelimit/token_bucket.go index 1f1381fd8dfe..1e84f799b986 100644 --- a/libbeat/processors/ratelimit/token_bucket.go +++ b/libbeat/processors/ratelimit/token_bucket.go @@ -20,13 +20,13 @@ package ratelimit import ( "fmt" "sync" + "sync/atomic" "time" "github.com/jonboulle/clockwork" "github.com/elastic/go-concert/unison" - "github.com/elastic/beats/v7/libbeat/common/atomic" "github.com/elastic/elastic-agent-libs/logp" ) @@ -50,7 +50,7 @@ type tokenBucket struct { gc struct { thresholds tokenBucketGCConfig metrics struct { - numCalls atomic.Uint + numCalls atomic.Uint64 } } @@ -93,7 +93,7 @@ func newTokenBucket(config algoConfig) (algorithm, error) { gc: struct { thresholds tokenBucketGCConfig metrics struct { - numCalls atomic.Uint + numCalls atomic.Uint64 } }{ thresholds: tokenBucketGCConfig{ @@ -112,7 +112,7 @@ func (t *tokenBucket) IsAllowed(key uint64) bool { b := t.getBucket(key) allowed := b.withdraw() - t.gc.metrics.numCalls.Inc() + t.gc.metrics.numCalls.Add(1) return allowed } @@ -126,6 +126,7 @@ func (t *tokenBucket) getBucket(key uint64) *bucket { tokens: t.depth, lastReplenish: t.clock.Now(), }) + //nolint:errcheck // ignore b := v.(*bucket) if exists { @@ -154,7 +155,7 @@ func (b *bucket) replenish(rate rate, clock clockwork.Clock) { func (t *tokenBucket) runGC() { // Don't run GC if thresholds haven't been crossed. - if t.gc.metrics.numCalls.Load() < t.gc.thresholds.NumCalls { + if t.gc.metrics.numCalls.Load() < uint64(t.gc.thresholds.NumCalls) { return } @@ -171,7 +172,9 @@ func (t *tokenBucket) runGC() { toDelete := make([]uint64, 0) numBucketsBefore := 0 t.buckets.Range(func(k, v interface{}) bool { + //nolint:errcheck // ignore key := k.(uint64) + //nolint:errcheck // ignore b := v.(*bucket) b.replenish(t.limit, t.clock) @@ -190,9 +193,9 @@ func (t *tokenBucket) runGC() { } // Reset GC metrics - t.gc.metrics.numCalls = atomic.MakeUint(0) + t.gc.metrics.numCalls = atomic.Uint64{} - gcDuration := time.Now().Sub(gcStartTime) + gcDuration := time.Since(gcStartTime) numBucketsDeleted := len(toDelete) numBucketsAfter := numBucketsBefore - numBucketsDeleted t.logger.Debugf("gc duration: %v, buckets: (before: %v, deleted: %v, after: %v)", diff --git a/libbeat/processors/syslog/syslog.go b/libbeat/processors/syslog/syslog.go index 96c21d3d7738..9a6e71fcca3f 100644 --- a/libbeat/processors/syslog/syslog.go +++ b/libbeat/processors/syslog/syslog.go @@ -22,9 +22,9 @@ import ( "errors" "fmt" "strconv" + "sync/atomic" "github.com/elastic/beats/v7/libbeat/beat" - "github.com/elastic/beats/v7/libbeat/common/atomic" "github.com/elastic/beats/v7/libbeat/common/cfgtype" "github.com/elastic/beats/v7/libbeat/common/jsontransform" "github.com/elastic/beats/v7/libbeat/processors" @@ -43,7 +43,7 @@ const ( ) // instanceID is used to assign each instance a unique monitoring namespace. -var instanceID = atomic.MakeUint32(0) +var instanceID atomic.Uint32 // config defines the configuration for this processor. type config struct { @@ -114,7 +114,7 @@ func New(c *conf.C) (beat.Processor, error) { return nil, fmt.Errorf("fail to unpack the "+procName+" processor configuration: %w", err) } - id := int(instanceID.Inc()) + id := int(instanceID.Add(1)) log := logp.NewLogger(logName).With("instance_id", id) registryName := logName + "." + strconv.Itoa(id) diff --git a/libbeat/publisher/pipeline/client.go b/libbeat/publisher/pipeline/client.go index af756213a632..3048ec4a0017 100644 --- a/libbeat/publisher/pipeline/client.go +++ b/libbeat/publisher/pipeline/client.go @@ -19,10 +19,10 @@ package pipeline import ( "sync" + "sync/atomic" "time" "github.com/elastic/beats/v7/libbeat/beat" - "github.com/elastic/beats/v7/libbeat/common/atomic" "github.com/elastic/beats/v7/libbeat/processors" "github.com/elastic/beats/v7/libbeat/publisher" "github.com/elastic/beats/v7/libbeat/publisher/queue" @@ -41,8 +41,7 @@ type client struct { canDrop bool // Open state, signaling, and sync primitives for coordinating client Close. - isOpen atomic.Bool // set to false during shutdown, such that no new events will be accepted anymore. - closeOnce sync.Once // closeOnce ensure that the client shutdown sequence is only executed once + isOpen atomic.Bool // set to false during shutdown, such that no new events will be accepted anymore. observer observer eventListener beat.EventListener @@ -204,12 +203,12 @@ func newClientCloseWaiter(timeout time.Duration) *clientCloseWaiter { func (w *clientCloseWaiter) AddEvent(_ beat.Event, published bool) { if published { - w.events.Inc() + w.events.Add(1) } } func (w *clientCloseWaiter) ACKEvents(n int) { - value := w.events.Sub(uint32(n)) + value := w.events.Add(^uint32(n - 1)) if value != 0 { return } diff --git a/libbeat/publisher/pipeline/client_worker_test.go b/libbeat/publisher/pipeline/client_worker_test.go index 97692b2aada8..ed97cd11ac83 100644 --- a/libbeat/publisher/pipeline/client_worker_test.go +++ b/libbeat/publisher/pipeline/client_worker_test.go @@ -22,6 +22,7 @@ import ( "math" "strings" "sync" + "sync/atomic" "testing" "testing/quick" "time" @@ -30,7 +31,6 @@ import ( "github.com/stretchr/testify/require" - "github.com/elastic/beats/v7/libbeat/common/atomic" "github.com/elastic/beats/v7/libbeat/internal/testutil" "github.com/elastic/beats/v7/libbeat/outputs" "github.com/elastic/beats/v7/libbeat/publisher" @@ -48,7 +48,7 @@ func TestMakeClientWorker(t *testing.T) { err := quick.Check(func(i uint) bool { numBatches := 300 + (i % 100) // between 300 and 399 - var numEvents uint + var numEvents uint64 logger := makeBufLogger(t) @@ -56,9 +56,9 @@ func TestMakeClientWorker(t *testing.T) { retryer := newStandaloneRetryer(workQueue) defer retryer.close() - var published atomic.Uint + var published atomic.Uint64 publishFn := func(batch publisher.Batch) error { - published.Add(uint(len(batch.Events()))) + published.Add(uint64(len(batch.Events()))) return nil } @@ -69,7 +69,7 @@ func TestMakeClientWorker(t *testing.T) { for i := uint(0); i < numBatches; i++ { batch := randomBatch(50, 150).withRetryer(retryer) - numEvents += uint(len(batch.Events())) + numEvents += uint64(len(batch.Events())) workQueue <- batch } @@ -82,7 +82,7 @@ func TestMakeClientWorker(t *testing.T) { }) if !success { logger.Flush() - t.Logf("numBatches = %v, numEvents = %v, published = %v", numBatches, numEvents, published) + t.Logf("numBatches = %v, numEvents = %v, published = %v", numBatches, numEvents, published.Load()) } return success }, nil) @@ -140,9 +140,9 @@ func TestReplaceClientWorker(t *testing.T) { }() // Publish at least 1 batch worth of events but no more than 20% events - publishLimit := uint(math.Max(minEventsInBatch, float64(numEvents)*0.2)) + publishLimit := uint64(math.Max(minEventsInBatch, float64(numEvents)*0.2)) - var publishedFirst atomic.Uint + var publishedFirst atomic.Uint64 blockCtrl := make(chan struct{}) blockingPublishFn := func(batch publisher.Batch) error { // Emulate blocking. Upon unblocking the in-flight batch that was @@ -152,7 +152,7 @@ func TestReplaceClientWorker(t *testing.T) { } count := len(batch.Events()) - publishedFirst.Add(uint(count)) + publishedFirst.Add(uint64(count)) t.Logf("#1 processed batch: %v (%v)", batch.(*mockBatch).events[0].Content.Private, count) return nil } @@ -176,10 +176,10 @@ func TestReplaceClientWorker(t *testing.T) { close(blockCtrl) // Start new worker to drain work queue - var publishedLater atomic.Uint + var publishedLater atomic.Uint64 countingPublishFn := func(batch publisher.Batch) error { count := len(batch.Events()) - publishedLater.Add(uint(count)) + publishedLater.Add(uint64(count)) t.Logf("#2 processed batch: %v (%v)", batch.(*mockBatch).events[0].Content.Private, count) return nil } @@ -212,7 +212,7 @@ func TestMakeClientTracer(t *testing.T) { testutil.SeedPRNG(t) numBatches := 10 - var numEvents uint + var numEvents uint64 logger := makeBufLogger(t) @@ -220,9 +220,9 @@ func TestMakeClientTracer(t *testing.T) { retryer := newStandaloneRetryer(workQueue) defer retryer.close() - var published atomic.Uint + var published atomic.Uint64 publishFn := func(batch publisher.Batch) error { - published.Add(uint(len(batch.Events()))) + published.Add(uint64(len(batch.Events()))) return nil } @@ -236,7 +236,7 @@ func TestMakeClientTracer(t *testing.T) { for i := 0; i < numBatches; i++ { batch := randomBatch(10, 15).withRetryer(retryer) - numEvents += uint(len(batch.Events())) + numEvents += uint64(len(batch.Events())) workQueue <- batch } @@ -248,7 +248,7 @@ func TestMakeClientTracer(t *testing.T) { return numEvents == published.Load() }) if !matches { - t.Errorf("expected %d events, got %d", numEvents, published) + t.Errorf("expected %d events, got %d", numEvents, published.Load()) } recorder.Flush(nil) diff --git a/libbeat/publisher/pipeline/controller_test.go b/libbeat/publisher/pipeline/controller_test.go index 706c159e3d4a..5e48fbb79b8f 100644 --- a/libbeat/publisher/pipeline/controller_test.go +++ b/libbeat/publisher/pipeline/controller_test.go @@ -20,12 +20,12 @@ package pipeline import ( "fmt" "sync" + "sync/atomic" "testing" "testing/quick" "time" "github.com/elastic/beats/v7/libbeat/beat" - "github.com/elastic/beats/v7/libbeat/common/atomic" "github.com/elastic/beats/v7/libbeat/internal/testutil" "github.com/elastic/beats/v7/libbeat/outputs" "github.com/elastic/beats/v7/libbeat/publisher" @@ -64,9 +64,9 @@ func TestOutputReload(t *testing.T) { fmt.Sprintf("mem.events: %v", numEventsToPublish)) _ = queueConfig.Unpack(conf) - var publishedCount atomic.Uint + var publishedCount atomic.Uint64 countingPublishFn := func(batch publisher.Batch) error { - publishedCount.Add(uint(len(batch.Events()))) + publishedCount.Add(uint64(len(batch.Events()))) return nil } @@ -108,7 +108,7 @@ func TestOutputReload(t *testing.T) { timeout := 20 * time.Second return waitUntilTrue(timeout, func() bool { - return numEventsToPublish == publishedCount.Load() + return uint64(numEventsToPublish) == publishedCount.Load() }) }, &quick.Config{MaxCount: 25}) @@ -222,18 +222,19 @@ func TestQueueProducerBlocksUntilOutputIsSet(t *testing.T) { // block, because there is no queue, but they should become unblocked // once we set a nonempty output. const producerCount = 10 - remaining := atomic.MakeInt(producerCount) + var remaining atomic.Int64 + remaining.Store(producerCount) for i := 0; i < producerCount; i++ { go func() { controller.queueProducer(queue.ProducerConfig{}) - remaining.Dec() + remaining.Add(-1) }() } allStarted := waitUntilTrue(time.Second, func() bool { return len(controller.pendingRequests) == producerCount }) assert.True(t, allStarted, "All queueProducer requests should be saved as pending requests by outputController") - assert.Equal(t, producerCount, remaining.Load(), "No queueProducer request should return before an output is set") + assert.Equal(t, int64(producerCount), remaining.Load(), "No queueProducer request should return before an output is set") // Set the output, then ensure that it unblocks all the waiting goroutines. controller.Set(outputs.Group{ diff --git a/libbeat/publisher/pipeline/pipeline.go b/libbeat/publisher/pipeline/pipeline.go index a5a13a0584ea..6297f7b7ee64 100644 --- a/libbeat/publisher/pipeline/pipeline.go +++ b/libbeat/publisher/pipeline/pipeline.go @@ -26,7 +26,6 @@ import ( "github.com/elastic/beats/v7/libbeat/beat" "github.com/elastic/beats/v7/libbeat/common/acker" - "github.com/elastic/beats/v7/libbeat/common/atomic" "github.com/elastic/beats/v7/libbeat/common/reload" "github.com/elastic/beats/v7/libbeat/outputs" "github.com/elastic/beats/v7/libbeat/publisher" @@ -211,13 +210,13 @@ func (p *Pipeline) ConnectWith(cfg beat.ClientConfig) (beat.Client, error) { client := &client{ logger: p.monitors.Logger, - isOpen: atomic.MakeBool(true), clientListener: cfg.ClientListener, processors: processors, eventFlags: eventFlags, canDrop: canDrop, observer: p.observer, } + client.isOpen.Store(true) ackHandler := cfg.EventListener diff --git a/libbeat/publisher/pipeline/pipeline_test.go b/libbeat/publisher/pipeline/pipeline_test.go index a8cf34b895aa..bd374c3c87bd 100644 --- a/libbeat/publisher/pipeline/pipeline_test.go +++ b/libbeat/publisher/pipeline/pipeline_test.go @@ -20,10 +20,10 @@ package pipeline import ( "runtime" "sync" + "sync/atomic" "testing" "github.com/elastic/beats/v7/libbeat/beat" - "github.com/elastic/beats/v7/libbeat/common/atomic" "github.com/elastic/beats/v7/libbeat/publisher/queue" "github.com/elastic/beats/v7/libbeat/tests/resources" "github.com/elastic/elastic-agent-libs/mapstr" @@ -79,7 +79,7 @@ func TestPipelineAcceptsAnyNumberOfClients(t *testing.T) { // close method is called, this ID is returned func makeDiscardQueue() queue.Queue { var wg sync.WaitGroup - producerID := atomic.NewInt(0) + var producerID atomic.Int64 return &testQueue{ close: func() error { @@ -92,7 +92,7 @@ func makeDiscardQueue() queue.Queue { }, producer: func(cfg queue.ProducerConfig) queue.Producer { - producerID.Inc() + producerID.Add(1) // count is a counter that increments on every published event // it's also the returned Event ID @@ -231,11 +231,11 @@ func makeTestQueue() queue.Queue { func blockingProducer(_ queue.ProducerConfig) queue.Producer { sig := make(chan struct{}) - waiting := atomic.MakeInt(0) + var waiting atomic.Int64 return &testProducer{ publish: func(_ bool, _ queue.Entry) (queue.EntryID, bool) { - waiting.Inc() + waiting.Add(1) <-sig return 0, false }, diff --git a/libbeat/publisher/pipeline/stress/gen.go b/libbeat/publisher/pipeline/stress/gen.go index 2a4d8c72ef0a..7fdf17bd27b0 100644 --- a/libbeat/publisher/pipeline/stress/gen.go +++ b/libbeat/publisher/pipeline/stress/gen.go @@ -22,6 +22,7 @@ import ( "fmt" "runtime/pprof" "sync" + "sync/atomic" "time" "github.com/elastic/elastic-agent-libs/logp" @@ -29,7 +30,6 @@ import ( "github.com/elastic/beats/v7/libbeat/beat" "github.com/elastic/beats/v7/libbeat/common/acker" - "github.com/elastic/beats/v7/libbeat/common/atomic" ) type generateConfig struct { @@ -97,7 +97,7 @@ func generate( done := make(chan struct{}) defer close(done) - count := atomic.MakeUint64(0) + var count atomic.Uint64 var wg sync.WaitGroup defer wg.Wait() @@ -148,7 +148,7 @@ func generate( Fields: mapstr.M{ "id": id, "hello": "world", - "count": count, + "count": count.Load(), // TODO: more custom event generation? }, @@ -156,7 +156,7 @@ func generate( client.Publish(event) - total := count.Inc() + total := count.Add(1) if config.MaxEvents > 0 && total == config.MaxEvents { break } diff --git a/libbeat/publisher/pipeline/stress/sig.go b/libbeat/publisher/pipeline/stress/sig.go index 537fc9c633bb..d6d03f0c3d13 100644 --- a/libbeat/publisher/pipeline/stress/sig.go +++ b/libbeat/publisher/pipeline/stress/sig.go @@ -17,7 +17,7 @@ package stress -import "github.com/elastic/beats/v7/libbeat/common/atomic" +import "sync/atomic" type closeSignaler struct { active atomic.Bool @@ -25,14 +25,15 @@ type closeSignaler struct { } func newCloseSignaler() *closeSignaler { - return &closeSignaler{ - active: atomic.MakeBool(true), - done: make(chan struct{}), + cs := &closeSignaler{ + done: make(chan struct{}), } + cs.active.Store(true) + return cs } func (s *closeSignaler) Close() { - if act := s.active.Swap(false); act { + if s.active.Swap(false) { close(s.done) } } diff --git a/libbeat/publisher/testing/connector.go b/libbeat/publisher/testing/connector.go index ddf48cc126f9..967f86ebe28a 100644 --- a/libbeat/publisher/testing/connector.go +++ b/libbeat/publisher/testing/connector.go @@ -18,15 +18,16 @@ package testing import ( + "sync/atomic" + "github.com/elastic/beats/v7/libbeat/beat" - "github.com/elastic/beats/v7/libbeat/common/atomic" ) // ClientCounter can be used to create a beat.PipelineConnector that count // pipeline connects and disconnects. type ClientCounter struct { - total atomic.Int - active atomic.Int + total atomic.Int64 + active atomic.Int64 } // FakeConnector implements the beat.PipelineConnector interface. @@ -111,21 +112,21 @@ func ChClient(ch chan beat.Event) beat.Client { } // Active returns the number of currently active connections. -func (c *ClientCounter) Active() int { return c.active.Load() } +func (c *ClientCounter) Active() int { return int(c.active.Load()) } // Total returns the total number of calls to Connect. -func (c *ClientCounter) Total() int { return c.total.Load() } +func (c *ClientCounter) Total() int { return int(c.total.Load()) } // BuildConnector create a pipeline that updates the active and tocal // connection counters on Connect and Close calls. func (c *ClientCounter) BuildConnector() beat.PipelineConnector { return FakeConnector{ ConnectFunc: func(_ beat.ClientConfig) (beat.Client, error) { - c.total.Inc() - c.active.Inc() + c.total.Add(1) + c.active.Add(1) return &FakeClient{ CloseFunc: func() error { - c.active.Dec() + c.active.Add(-1) return nil }, }, nil diff --git a/libbeat/tests/integration/framework.go b/libbeat/tests/integration/framework.go index 904fc1e302a9..aa05d6ff0e6b 100644 --- a/libbeat/tests/integration/framework.go +++ b/libbeat/tests/integration/framework.go @@ -37,13 +37,12 @@ import ( "strconv" "strings" "sync" + "sync/atomic" "testing" "time" "github.com/gofrs/uuid/v5" "github.com/stretchr/testify/require" - - "github.com/elastic/beats/v7/libbeat/common/atomic" ) type BeatProc struct { @@ -189,7 +188,7 @@ func (b *BeatProc) Start(args ...string) { b.fullPath = fullPath b.Args = append(b.baseArgs, args...) - done := atomic.MakeBool(false) + var done atomic.Bool wg := sync.WaitGroup{} if b.RestartOnBeatOnExit { wg.Add(1) diff --git a/metricbeat/mb/module/runner_group_test.go b/metricbeat/mb/module/runner_group_test.go index 1d462359968e..2cd6e6cc8b5c 100644 --- a/metricbeat/mb/module/runner_group_test.go +++ b/metricbeat/mb/module/runner_group_test.go @@ -19,13 +19,13 @@ package module import ( "fmt" + "sync/atomic" "testing" "github.com/stretchr/testify/assert" "github.com/stretchr/testify/require" "github.com/elastic/beats/v7/libbeat/cfgfile" - "github.com/elastic/beats/v7/libbeat/common/atomic" "github.com/elastic/beats/v7/libbeat/common/diagnostics" ) @@ -55,19 +55,19 @@ func (fr *fakeRunnerDiag) Diagnostics() []diagnostics.DiagnosticSetup { type fakeRunner struct { id int - startCounter *atomic.Int - stopCounter *atomic.Int + startCounter *atomic.Int64 + stopCounter *atomic.Int64 } func (fr *fakeRunner) Start() { if fr.startCounter != nil { - fr.startCounter.Inc() + fr.startCounter.Add(1) } } func (fr *fakeRunner) Stop() { if fr.stopCounter != nil { - fr.stopCounter.Inc() + fr.stopCounter.Add(1) } } @@ -76,15 +76,14 @@ func (fr *fakeRunner) String() string { } func TestStartStop(t *testing.T) { - startCounter := atomic.NewInt(0) - stopCounter := atomic.NewInt(0) + var startCounter, stopCounter atomic.Int64 runners := make([]cfgfile.Runner, 0, fakeRunnersNum) for i := 0; i < fakeRunnersNum; i++ { runners = append(runners, &fakeRunner{ id: i, - startCounter: startCounter, - stopCounter: stopCounter, + startCounter: &startCounter, + stopCounter: &stopCounter, }) } @@ -93,8 +92,8 @@ func TestStartStop(t *testing.T) { runnerGroup.Stop() - assert.Equal(t, fakeRunnersNum, startCounter.Load()) - assert.Equal(t, fakeRunnersNum, stopCounter.Load()) + assert.Equal(t, int64(fakeRunnersNum), startCounter.Load()) + assert.Equal(t, int64(fakeRunnersNum), stopCounter.Load()) } func TestDiagnosticsUnsupported(t *testing.T) { @@ -102,8 +101,8 @@ func TestDiagnosticsUnsupported(t *testing.T) { for i := 0; i < fakeRunnersNum; i++ { runners = append(runners, &fakeRunner{ id: i, - startCounter: atomic.NewInt(0), - stopCounter: atomic.NewInt(0), + startCounter: &atomic.Int64{}, + stopCounter: &atomic.Int64{}, }) } diff --git a/packetbeat/sniffer/sniffer.go b/packetbeat/sniffer/sniffer.go index d8043032a64a..24c77180b46a 100644 --- a/packetbeat/sniffer/sniffer.go +++ b/packetbeat/sniffer/sniffer.go @@ -25,6 +25,7 @@ import ( "os" "runtime" "strings" + "sync/atomic" "time" "github.com/google/gopacket" @@ -33,7 +34,6 @@ import ( "github.com/google/gopacket/pcapgo" "golang.org/x/sync/errgroup" - "github.com/elastic/beats/v7/libbeat/common/atomic" "github.com/elastic/elastic-agent-libs/logp" "github.com/elastic/beats/v7/packetbeat/config" @@ -51,7 +51,7 @@ type Sniffer struct { type sniffer struct { config config.InterfaceConfig - state atomic.Int32 // store snifferState + state *atomic.Int32 // store snifferState // device is the first active device after calling New. // It is not updated by default route polling. @@ -103,13 +103,14 @@ func New(id string, testMode bool, _ string, decoders map[string]Decoders, inter return nil, fmt.Errorf("no decoder for %s", iface.Device) } child := sniffer{ - state: atomic.MakeInt32(snifferInactive), + state: &atomic.Int32{}, followDefault: iface.PollDefaultRoute > 0 && strings.HasPrefix(iface.Device, "default_route"), id: id, idx: i, decoders: dec, log: s.log, } + child.state.Store(snifferInactive) s.log.Debugf("interface: %d, BPF filter: '%s'", i, iface.BpfFilter) @@ -373,7 +374,7 @@ func (s *sniffer) sniffHandle(ctx context.Context, handle snifferHandle, dec *de // Mark inactive sniffer as active. In case of the sniffer/packetbeat closing // before/while Run is executed, the state will be snifferClosing. // => return if state is already snifferClosing. - if !s.state.CAS(snifferInactive, snifferActive) { + if !s.state.CompareAndSwap(snifferInactive, snifferActive) { return nil } defer s.state.Store(snifferInactive) diff --git a/winlogbeat/beater/acker.go b/winlogbeat/beater/acker.go index e9cc2e77c33c..d35a01664846 100644 --- a/winlogbeat/beater/acker.go +++ b/winlogbeat/beater/acker.go @@ -20,20 +20,20 @@ package beater import ( "context" "sync" + "sync/atomic" - "github.com/elastic/beats/v7/libbeat/common/atomic" "github.com/elastic/beats/v7/winlogbeat/checkpoint" ) type eventACKer struct { - active *atomic.Int + active *atomic.Int64 wg *sync.WaitGroup checkpoint *checkpoint.Checkpoint } func newEventACKer(checkpoint *checkpoint.Checkpoint) *eventACKer { return &eventACKer{ - active: atomic.NewInt(0), + active: &atomic.Int64{}, wg: &sync.WaitGroup{}, checkpoint: checkpoint, } @@ -55,7 +55,7 @@ func (a *eventACKer) ACKEvents(data []interface{}) { } // Mark events as done (subtract). - a.active.Add(-1 * len(data)) + a.active.Add(-1 * int64(len(data))) a.wg.Add(-1 * len(data)) } @@ -71,11 +71,11 @@ func (a *eventACKer) Wait(ctx context.Context) { // Add adds to the number of active events. func (a *eventACKer) Add(delta int) { - a.active.Add(delta) + a.active.Add(int64(delta)) a.wg.Add(delta) } // Active returns the number of active events (published but not yet ACKed). func (a *eventACKer) Active() int { - return a.active.Load() + return int(a.active.Load()) } diff --git a/winlogbeat/sys/wineventlog/renderer_test.go b/winlogbeat/sys/wineventlog/renderer_test.go index 339122d8a297..01089b5a112e 100644 --- a/winlogbeat/sys/wineventlog/renderer_test.go +++ b/winlogbeat/sys/wineventlog/renderer_test.go @@ -26,13 +26,13 @@ import ( "runtime" "strconv" "strings" + "sync/atomic" "testing" "text/template" "time" "github.com/stretchr/testify/assert" - "github.com/elastic/beats/v7/libbeat/common/atomic" "github.com/elastic/beats/v7/winlogbeat/sys/winevent" "github.com/elastic/elastic-agent-libs/logp" ) @@ -297,7 +297,7 @@ func BenchmarkRenderer(b *testing.B) { defer itr.Close() defer r.Close() - count := atomic.NewUint64(0) + count := atomic.Uint64{} start := time.Now() b.ResetTimer() @@ -314,7 +314,7 @@ func BenchmarkRenderer(b *testing.B) { b.Fatal(err) } - count.Inc() + count.Add(1) } elapsed := time.Since(start) @@ -326,7 +326,7 @@ func BenchmarkRenderer(b *testing.B) { defer itr.Close() defer r.Close() - count := atomic.NewUint64(0) + var count atomic.Uint64 start := time.Now() b.ResetTimer() @@ -343,7 +343,7 @@ func BenchmarkRenderer(b *testing.B) { if err != nil { b.Fatal(err) } - count.Inc() + count.Add(1) } }) diff --git a/x-pack/filebeat/input/awss3/metrics_test.go b/x-pack/filebeat/input/awss3/metrics_test.go index e153d321e9f1..33d3b9a513b5 100644 --- a/x-pack/filebeat/input/awss3/metrics_test.go +++ b/x-pack/filebeat/input/awss3/metrics_test.go @@ -5,12 +5,12 @@ package awss3 import ( + "sync/atomic" "testing" "time" "github.com/stretchr/testify/assert" - "github.com/elastic/beats/v7/libbeat/common/atomic" "github.com/elastic/elastic-agent-libs/monitoring" ) diff --git a/x-pack/filebeat/input/entityanalytics/internal/kvstore/tracker.go b/x-pack/filebeat/input/entityanalytics/internal/kvstore/tracker.go index b18229b77954..71abb10d137f 100644 --- a/x-pack/filebeat/input/entityanalytics/internal/kvstore/tracker.go +++ b/x-pack/filebeat/input/entityanalytics/internal/kvstore/tracker.go @@ -6,10 +6,10 @@ package kvstore import ( "context" + "sync/atomic" "github.com/elastic/beats/v7/libbeat/beat" "github.com/elastic/beats/v7/libbeat/common/acker" - "github.com/elastic/beats/v7/libbeat/common/atomic" ) // TxTracker implements a transaction tracker. Individual beat events which @@ -17,20 +17,20 @@ import ( // ACK-ed, the pending count is decremented (see NewTxACKHandler). Calling Wait // will block until all events are ACK-ed or the parent context is cancelled. type TxTracker struct { - pending atomic.Int + pending atomic.Int64 ctx context.Context cancel context.CancelFunc } // Add increments the pending count. func (t *TxTracker) Add() { - t.pending.Inc() + t.pending.Add(1) } // Ack decrements the pending count. If pending goes to zero, then the // context on TxTracker is cancelled. func (t *TxTracker) Ack() { - if t.pending.Dec() == 0 { + if t.pending.Add(-1) == 0 { t.cancel() } } diff --git a/x-pack/filebeat/input/entityanalytics/internal/kvstore/tracker_test.go b/x-pack/filebeat/input/entityanalytics/internal/kvstore/tracker_test.go index 7b452e21ae89..7741fa1e595e 100644 --- a/x-pack/filebeat/input/entityanalytics/internal/kvstore/tracker_test.go +++ b/x-pack/filebeat/input/entityanalytics/internal/kvstore/tracker_test.go @@ -15,7 +15,7 @@ import ( func TestTxTracker_Ack(t *testing.T) { txTracker := NewTxTracker(context.Background()) - txTracker.pending.Inc() + txTracker.pending.Add(1) txTracker.Ack() @@ -25,9 +25,9 @@ func TestTxTracker_Ack(t *testing.T) { func TestTxTracker_Add(t *testing.T) { txTracker := NewTxTracker(context.Background()) - require.Equal(t, 0, txTracker.pending.Load()) + require.Equal(t, int64(0), txTracker.pending.Load()) txTracker.Add() - require.Equal(t, 1, txTracker.pending.Load()) + require.Equal(t, int64(1), txTracker.pending.Load()) } func TestTxTracker_Wait(t *testing.T) { @@ -43,7 +43,7 @@ func TestTxACKHandler(t *testing.T) { handler := NewTxACKHandler() txTracker.Add() - require.Equal(t, 1, txTracker.pending.Load()) + require.Equal(t, int64(1), txTracker.pending.Load()) handler.AddEvent(beat.Event{ Private: txTracker, @@ -63,7 +63,7 @@ func TestTxACKHandler(t *testing.T) { handler := NewTxACKHandler() txTracker.Add() - require.Equal(t, 1, txTracker.pending.Load()) + require.Equal(t, int64(1), txTracker.pending.Load()) handler.AddEvent(beat.Event{ Private: txTracker, @@ -71,6 +71,6 @@ func TestTxACKHandler(t *testing.T) { txTracker.Wait() - require.Equal(t, 1, txTracker.pending.Load()) + require.Equal(t, int64(1), txTracker.pending.Load()) }) } diff --git a/x-pack/filebeat/input/entityanalytics/internal/kvstore/transaction.go b/x-pack/filebeat/input/entityanalytics/internal/kvstore/transaction.go index 7f32429a4e96..c62155d27fbc 100644 --- a/x-pack/filebeat/input/entityanalytics/internal/kvstore/transaction.go +++ b/x-pack/filebeat/input/entityanalytics/internal/kvstore/transaction.go @@ -8,10 +8,9 @@ import ( "encoding/json" "errors" "fmt" + "sync/atomic" "go.etcd.io/bbolt" - - "github.com/elastic/beats/v7/libbeat/common/atomic" ) var ( @@ -126,7 +125,7 @@ func (t *Transaction) Delete(bucket, key []byte) error { // Commit will write any changes to disk. For read-only transactions, calling // Commit will route to Rollback. func (t *Transaction) Commit() error { - if !t.closed.CAS(false, true) { + if !t.closed.CompareAndSwap(false, true) { return nil } if !t.writeable { @@ -138,7 +137,7 @@ func (t *Transaction) Commit() error { // Rollback closes the transaction. For write transactions, all updates made // within the transaction will be discarded. func (t *Transaction) Rollback() error { - if !t.closed.CAS(false, true) { + if !t.closed.CompareAndSwap(false, true) { return nil } return t.tx.Rollback() diff --git a/x-pack/filebeat/input/gcppubsub/pubsub_test.go b/x-pack/filebeat/input/gcppubsub/pubsub_test.go index 7981a3ee7724..16fdbf1ebbd1 100644 --- a/x-pack/filebeat/input/gcppubsub/pubsub_test.go +++ b/x-pack/filebeat/input/gcppubsub/pubsub_test.go @@ -12,6 +12,7 @@ import ( "os" "strconv" "sync" + "sync/atomic" "testing" "time" @@ -23,7 +24,6 @@ import ( "github.com/elastic/beats/v7/filebeat/channel" "github.com/elastic/beats/v7/filebeat/input" "github.com/elastic/beats/v7/libbeat/beat" - "github.com/elastic/beats/v7/libbeat/common/atomic" "github.com/elastic/beats/v7/libbeat/tests/compose" "github.com/elastic/beats/v7/libbeat/tests/resources" conf "github.com/elastic/elastic-agent-libs/config" @@ -247,6 +247,7 @@ func runTestWithACKer(t *testing.T, cfg *conf.C, onEvent eventHandler, run func( if err != nil { t.Fatal(err) } + //nolint:errcheck // ignore pubsubInput := in.(*pubsubInput) defer pubsubInput.Stop() @@ -421,13 +422,14 @@ func TestRunStop(t *testing.T) { func TestEndToEndACK(t *testing.T) { cfg := defaultTestConfig() - var count atomic.Int + var count atomic.Int64 seen := make(map[string]struct{}) // ACK every other message halfAcker := func(ev beat.Event, clientConfig beat.ClientConfig) bool { + //nolint:errcheck // ignore msg := ev.Private.(*pubsub.Message) seen[msg.ID] = struct{}{} - if count.Inc()&1 != 0 { + if count.Add(1)&1 != 0 { // Nack will result in the Message being redelivered more quickly than if it were allowed to expire. msg.Nack() return false @@ -453,6 +455,7 @@ func TestEndToEndACK(t *testing.T) { assert.Len(t, events, len(seen)) got := make(map[string]struct{}) for _, ev := range events { + //nolint:errcheck // ignore msg := ev.Private.(*pubsub.Message) got[msg.ID] = struct{}{} } diff --git a/x-pack/filebeat/input/netflow/decoder/atomic/bool.go b/x-pack/filebeat/input/netflow/decoder/atomic/bool.go deleted file mode 100644 index b294cc6c395c..000000000000 --- a/x-pack/filebeat/input/netflow/decoder/atomic/bool.go +++ /dev/null @@ -1,30 +0,0 @@ -// Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one -// or more contributor license agreements. Licensed under the Elastic License; -// you may not use this file except in compliance with the Elastic License. - -package atomic - -import "sync/atomic" - -type Bool struct { - value uint32 -} - -func (b *Bool) Store(value bool) { - atomic.StoreUint32(&b.value, encodeBool(value)) -} - -func (b *Bool) CAS(old bool, new bool) (swapped bool) { - return atomic.CompareAndSwapUint32(&b.value, encodeBool(old), encodeBool(new)) -} - -func (b *Bool) Load() (value bool) { - return atomic.LoadUint32(&b.value) != 0 -} - -func encodeBool(value bool) (result uint32) { - if value { - result = 1 - } - return -} diff --git a/x-pack/filebeat/input/netflow/decoder/v9/session.go b/x-pack/filebeat/input/netflow/decoder/v9/session.go index 492576f6b962..e72fa1ab80a6 100644 --- a/x-pack/filebeat/input/netflow/decoder/v9/session.go +++ b/x-pack/filebeat/input/netflow/decoder/v9/session.go @@ -8,9 +8,9 @@ import ( "log" "net" "sync" + "sync/atomic" "time" - "github.com/elastic/beats/v7/x-pack/filebeat/input/netflow/decoder/atomic" "github.com/elastic/beats/v7/x-pack/filebeat/input/netflow/decoder/config" "github.com/elastic/beats/v7/x-pack/filebeat/input/netflow/decoder/template" ) @@ -83,7 +83,7 @@ func (s *SessionState) ExpireTemplates() (alive int, removed int) { var toDelete []TemplateKey s.mutex.RLock() for id, template := range s.Templates { - if !template.Delete.CAS(false, true) { + if !template.Delete.CompareAndSwap(false, true) { toDelete = append(toDelete, id) } } @@ -183,7 +183,7 @@ func (m *SessionMap) cleanup() (aliveSession int, removedSession int, aliveTempl a, r := session.ExpireTemplates() aliveTemplates += a removedTemplates += r - if !session.Delete.CAS(false, true) { + if !session.Delete.CompareAndSwap(false, true) { toDelete = append(toDelete, key) } } diff --git a/x-pack/heartbeat/monitors/browser/synthexec/execmultiplexer.go b/x-pack/heartbeat/monitors/browser/synthexec/execmultiplexer.go index f3684398a513..fe384ae15b23 100644 --- a/x-pack/heartbeat/monitors/browser/synthexec/execmultiplexer.go +++ b/x-pack/heartbeat/monitors/browser/synthexec/execmultiplexer.go @@ -5,12 +5,10 @@ package synthexec -import ( - "github.com/elastic/beats/v7/libbeat/common/atomic" -) +import "sync/atomic" type ExecMultiplexer struct { - eventCounter *atomic.Int + eventCounter *atomic.Int64 synthEvents chan *SynthEvent done chan struct{} } @@ -27,7 +25,7 @@ func (e *ExecMultiplexer) writeSynthEvent(se *SynthEvent) { if se.Type == JourneyStart { e.eventCounter.Store(-1) } - se.index = e.eventCounter.Inc() + se.index = int(e.eventCounter.Add(1)) e.synthEvents <- se } @@ -48,8 +46,10 @@ func (e *ExecMultiplexer) Wait() { } func NewExecMultiplexer() *ExecMultiplexer { + c := &atomic.Int64{} + c.Store(-1) // Start from -1 so first call to Inc returns 0 return &ExecMultiplexer{ - eventCounter: atomic.NewInt(-1), // Start from -1 so first call to Inc returns 0 + eventCounter: c, synthEvents: make(chan *SynthEvent), done: make(chan struct{}), } diff --git a/x-pack/metricbeat/module/cloudfoundry/v1.go b/x-pack/metricbeat/module/cloudfoundry/v1.go index f03f6a98ebb8..86610e0d6cbf 100644 --- a/x-pack/metricbeat/module/cloudfoundry/v1.go +++ b/x-pack/metricbeat/module/cloudfoundry/v1.go @@ -7,7 +7,8 @@ package cloudfoundry import ( - "github.com/elastic/beats/v7/libbeat/common/atomic" + "sync/atomic" + "github.com/elastic/beats/v7/metricbeat/mb" cfcommon "github.com/elastic/beats/v7/x-pack/libbeat/common/cloudfoundry" "github.com/elastic/elastic-agent-libs/logp" @@ -29,7 +30,6 @@ func newModuleV1(base mb.BaseModule, hub CloudfoundryHub, log *logp.Logger) (*Mo m := ModuleV1{ BaseModule: base, log: log, - running: atomic.MakeBool(false), } consumer, err := hub.DopplerConsumer(cfcommon.DopplerCallbacks{ Metric: m.callback, @@ -83,7 +83,7 @@ func (m *ModuleV1) callback(event cfcommon.Event) { // run ensures that the module is running with the passed subscription func (m *ModuleV1) run(s subscription) { - if !m.running.CAS(false, true) { + if !m.running.CompareAndSwap(false, true) { // Module is already running, queue subscription for current dispatcher. m.subscriptions <- s return From fd8107420d2c063a3f3a0e382e9d4b02006c4e64 Mon Sep 17 00:00:00 2001 From: ShourieG Date: Wed, 11 Dec 2024 08:02:42 +0530 Subject: [PATCH 35/48] [filebeat][streaming] - Added support for TLS & forward proxy configs for websockets (#41934) --- CHANGELOG.next.asciidoc | 1 + .../docs/inputs/input-streaming.asciidoc | 22 ++ x-pack/filebeat/input/streaming/config.go | 11 +- .../filebeat/input/streaming/input_manager.go | 2 +- x-pack/filebeat/input/streaming/input_test.go | 249 ++++++++++++++++++ .../input/streaming/testdata/certs/ca.crt | 21 ++ .../input/streaming/testdata/certs/cert.pem | 21 ++ .../input/streaming/testdata/certs/key.pem | 28 ++ x-pack/filebeat/input/streaming/websocket.go | 53 +++- 9 files changed, 402 insertions(+), 6 deletions(-) create mode 100644 x-pack/filebeat/input/streaming/testdata/certs/ca.crt create mode 100644 x-pack/filebeat/input/streaming/testdata/certs/cert.pem create mode 100644 x-pack/filebeat/input/streaming/testdata/certs/key.pem diff --git a/CHANGELOG.next.asciidoc b/CHANGELOG.next.asciidoc index bb6c4df0f627..dd4f19be3350 100644 --- a/CHANGELOG.next.asciidoc +++ b/CHANGELOG.next.asciidoc @@ -360,6 +360,7 @@ https://github.com/elastic/beats/compare/v8.8.1\...main[Check the HEAD diff] - Add evaluation state dump debugging option to CEL input. {pull}41335[41335] - Added support for retry configuration in GCS input. {issue}11580[11580] {pull}41862[41862] - Improve S3 polling mode states registry when using list prefix option. {pull}41869[41869] +- Add support for SSL and Proxy configurations for websoket type in streaming input. {pull}41934[41934] - AWS S3 input registry cleanup for untracked s3 objects. {pull}41694[41694] - The environment variable `BEATS_AZURE_EVENTHUB_INPUT_TRACING_ENABLED: true` enables internal logs tracer for the azure-eventhub input. {issue}41931[41931] {pull}41932[41932] diff --git a/x-pack/filebeat/docs/inputs/input-streaming.asciidoc b/x-pack/filebeat/docs/inputs/input-streaming.asciidoc index b80deda9c778..9a6f67e5bc49 100644 --- a/x-pack/filebeat/docs/inputs/input-streaming.asciidoc +++ b/x-pack/filebeat/docs/inputs/input-streaming.asciidoc @@ -349,6 +349,28 @@ The minimum time to wait between retries. This ensures that retries are spaced o The maximum time to wait between retries. This prevents the retry mechanism from becoming too slow, ensuring that the client does not wait indefinitely between retries. This is crucial in systems where timeouts or user experience are critical. For example, `wait_max` might be set to 10 seconds, meaning that even if the calculated backoff is greater than this, the client will wait at most 10 seconds before retrying. +[float] +=== `timeout` +Timeout is the maximum amount of time the websocket dialer will wait for a connection to be established. The default value is `180` seconds. + +[float] +==== `proxy_url` +This specifies the forward proxy URL to use for the connection. The `proxy_url` configuration is optional and can be used to configure the proxy settings for the connection. The `proxy_url` default value is set by `http.ProxyFromEnvironment` which reads the `HTTP_PROXY`, `HTTPS_PROXY`, and `NO_PROXY` environment variables. + +[float] +==== `proxy_headers` +This specifies the headers to be sent to the proxy server. The `proxy_headers` configuration is optional and can be used to configure the headers to be sent to the proxy server. + +[float] +==== `ssl` +This specifies the SSL configuration for the connection. The `ssl` configuration is optional and can be used to configure the SSL settings for the connection. The `ssl` configuration has the following subfields: + + - `certificate_authorities`: A list of root certificates to use for verifying the server's certificate. + - `certificate`: The (PEM encoded) certificate to use for client authentication. + - `key`: The (PEM encoded) private key to use for client authentication. + +If this is a self-signed certificate, the `certificate_authorities` field should be set to the certificate itself. + [float] === Metrics diff --git a/x-pack/filebeat/input/streaming/config.go b/x-pack/filebeat/input/streaming/config.go index 67ee6e1eb318..6ccaf0c73493 100644 --- a/x-pack/filebeat/input/streaming/config.go +++ b/x-pack/filebeat/input/streaming/config.go @@ -41,9 +41,8 @@ type config struct { Redact *redact `config:"redact"` // Retry is the configuration for retrying failed connections. Retry *retry `config:"retry"` - + // Transport is the common the transport config. Transport httpcommon.HTTPTransportSettings `config:",inline"` - // CrowdstrikeAppID is the value used to set the // appId request parameter in the FalconHose stream // discovery request. @@ -166,3 +165,11 @@ func checkURLScheme(c config) error { return fmt.Errorf("unknown stream type: %s", c.Type) } } + +func defaultConfig() config { + return config{ + Transport: httpcommon.HTTPTransportSettings{ + Timeout: 180 * time.Second, + }, + } +} diff --git a/x-pack/filebeat/input/streaming/input_manager.go b/x-pack/filebeat/input/streaming/input_manager.go index f20b867755b2..c685452c34f1 100644 --- a/x-pack/filebeat/input/streaming/input_manager.go +++ b/x-pack/filebeat/input/streaming/input_manager.go @@ -34,7 +34,7 @@ func NewInputManager(log *logp.Logger, store inputcursor.StateStore) InputManage } func cursorConfigure(cfg *conf.C) ([]inputcursor.Source, inputcursor.Input, error) { - src := &source{cfg: config{}} + src := &source{cfg: defaultConfig()} if err := cfg.Unpack(&src.cfg); err != nil { return nil, nil, err } diff --git a/x-pack/filebeat/input/streaming/input_test.go b/x-pack/filebeat/input/streaming/input_test.go index 6d382bdf6645..c11784ea3dbf 100644 --- a/x-pack/filebeat/input/streaming/input_test.go +++ b/x-pack/filebeat/input/streaming/input_test.go @@ -6,6 +6,7 @@ package streaming import ( "context" + "crypto/tls" "errors" "fmt" "net/http" @@ -41,6 +42,7 @@ type WebSocketHandler func(*testing.T, *websocket.Conn, []string) var inputTests = []struct { name string server func(*testing.T, WebSocketHandler, map[string]interface{}, []string) + proxyServer func(*testing.T, WebSocketHandler, map[string]interface{}, []string) *httptest.Server handler WebSocketHandler config map[string]interface{} response []string @@ -450,6 +452,140 @@ var inputTests = []struct { }, wantErr: fmt.Errorf("failed to establish WebSocket connection after 2 attempts with error websocket: bad handshake"), }, + { + name: "single_event_tls", + server: webSocketServerWithTLS(httptest.NewUnstartedServer), + handler: defaultHandler, + config: map[string]interface{}{ + "program": ` + bytes(state.response).decode_json().as(inner_body,{ + "events": [inner_body], + })`, + "ssl": map[string]interface{}{ + "enabled": true, + "certificate_authorities": []string{"testdata/certs/ca.crt"}, + "certificate": "testdata/certs/cert.pem", + "key": "testdata/certs/key.pem", + }, + }, + response: []string{` + { + "pps": { + "agent": "example.proofpoint.com", + "cid": "mmeng_uivm071" + }, + "ts": "2017-08-17T14:54:12.949180-07:00", + "data": "2017-08-17T14:54:12.949180-07:00 example sendmail[30641]:v7HLqYbx029423: to=/dev/null, ctladdr= (8/0),delay=00:00:00, xdelay=00:00:00, mailer=*file*, tls_verify=NONE, pri=35342,dsn=2.0.0, stat=Sent", + "sm": { + "tls": { + "verify": "NONE" + }, + "stat": "Sent", + "qid": "v7HLqYbx029423", + "dsn": "2.0.0", + "mailer": "*file*", + "to": [ + "/dev/null" + ], + "ctladdr": " (8/0)", + "delay": "00:00:00", + "xdelay": "00:00:00", + "pri": 35342 + }, + "id": "ZeYGULpZmL5N0151HN1OyA" + }`}, + want: []map[string]interface{}{ + { + "pps": map[string]interface{}{ + "agent": "example.proofpoint.com", + "cid": "mmeng_uivm071", + }, + "ts": "2017-08-17T14:54:12.949180-07:00", + "data": "2017-08-17T14:54:12.949180-07:00 example sendmail[30641]:v7HLqYbx029423: to=/dev/null, ctladdr= (8/0),delay=00:00:00, xdelay=00:00:00, mailer=*file*, tls_verify=NONE, pri=35342,dsn=2.0.0, stat=Sent", + "sm": map[string]interface{}{ + "tls": map[string]interface{}{ + "verify": "NONE", + }, + "stat": "Sent", + "qid": "v7HLqYbx029423", + "dsn": "2.0.0", + "mailer": "*file*", + "to": []interface{}{ + "/dev/null", + }, + "ctladdr": " (8/0)", + "delay": "00:00:00", + "xdelay": "00:00:00", + "pri": float64(35342), + }, + "id": "ZeYGULpZmL5N0151HN1OyA", + }, + }, + }, + { + name: "basic_proxy_forwarding", + proxyServer: newWebSocketProxyTestServer, + handler: defaultHandler, + config: map[string]interface{}{ + "program": ` + bytes(state.response).decode_json().as(inner_body,{ + "events": [inner_body], + })`, + }, + response: []string{` + { + "pps": { + "agent": "example.proofpoint.com", + "cid": "mmeng_uivm071" + }, + "ts": "2017-08-17T14:54:12.949180-07:00", + "data": "2017-08-17T14:54:12.949180-07:00 example sendmail[30641]:v7HLqYbx029423: to=/dev/null, ctladdr= (8/0),delay=00:00:00, xdelay=00:00:00, mailer=*file*, tls_verify=NONE, pri=35342,dsn=2.0.0, stat=Sent", + "sm": { + "tls": { + "verify": "NONE" + }, + "stat": "Sent", + "qid": "v7HLqYbx029423", + "dsn": "2.0.0", + "mailer": "*file*", + "to": [ + "/dev/null" + ], + "ctladdr": " (8/0)", + "delay": "00:00:00", + "xdelay": "00:00:00", + "pri": 35342 + }, + "id": "ZeYGULpZmL5N0151HN1OyA" + }`}, + want: []map[string]interface{}{ + { + "pps": map[string]interface{}{ + "agent": "example.proofpoint.com", + "cid": "mmeng_uivm071", + }, + "ts": "2017-08-17T14:54:12.949180-07:00", + "data": "2017-08-17T14:54:12.949180-07:00 example sendmail[30641]:v7HLqYbx029423: to=/dev/null, ctladdr= (8/0),delay=00:00:00, xdelay=00:00:00, mailer=*file*, tls_verify=NONE, pri=35342,dsn=2.0.0, stat=Sent", + "sm": map[string]interface{}{ + "tls": map[string]interface{}{ + "verify": "NONE", + }, + "stat": "Sent", + "qid": "v7HLqYbx029423", + "dsn": "2.0.0", + "mailer": "*file*", + "to": []interface{}{ + "/dev/null", + }, + "ctladdr": " (8/0)", + "delay": "00:00:00", + "xdelay": "00:00:00", + "pri": float64(35342), + }, + "id": "ZeYGULpZmL5N0151HN1OyA", + }, + }, + }, } var urlEvalTests = []struct { @@ -560,6 +696,9 @@ func TestInput(t *testing.T) { if test.server != nil { test.server(t, test.handler, test.config, test.response) } + if test.proxyServer != nil { + test.proxyServer(t, test.handler, test.config, test.response) + } cfg := conf.MustNewConfigFrom(test.config) @@ -771,6 +910,46 @@ func webSocketServerWithRetry(serve func(http.Handler) *httptest.Server) func(*t } } +// webSocketServerWithTLS simulates a WebSocket server with TLS based authentication. +func webSocketServerWithTLS(serve func(http.Handler) *httptest.Server) func(*testing.T, WebSocketHandler, map[string]interface{}, []string) { + return func(t *testing.T, handler WebSocketHandler, config map[string]interface{}, response []string) { + server := serve(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { + upgrader := websocket.Upgrader{ + CheckOrigin: func(r *http.Request) bool { + return true + }, + } + + conn, err := upgrader.Upgrade(w, r, nil) + if err != nil { + t.Fatalf("error upgrading connection to WebSocket: %v", err) + return + } + + handler(t, conn, response) + })) + //nolint:gosec // there is no need to use a secure cert for testing + server.TLS = &tls.Config{ + Certificates: []tls.Certificate{generateSelfSignedCert(t)}, + } + server.StartTLS() + + if config["url"] == nil { + config["url"] = "ws" + server.URL[4:] + } + t.Cleanup(server.Close) + } +} + +// generateSelfSignedCert returns a self-signed certificate for testing purposes based on the dummy certs in the testdata directory +func generateSelfSignedCert(t *testing.T) tls.Certificate { + cert, err := tls.LoadX509KeyPair("testdata/certs/cert.pem", "testdata/certs/key.pem") + if err != nil { + t.Fatalf("failed to generate self-signed cert: %v", err) + } + return cert +} + // defaultHandler is a default handler for WebSocket connections. func defaultHandler(t *testing.T, conn *websocket.Conn, response []string) { for _, r := range response { @@ -780,3 +959,73 @@ func defaultHandler(t *testing.T, conn *websocket.Conn, response []string) { } } } + +// webSocketTestServer creates a WebSocket target server that communicates with the proxy handler. +func webSocketTestServer(t *testing.T, handler WebSocketHandler, response []string) *httptest.Server { + return httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { + upgrader := websocket.Upgrader{ + CheckOrigin: func(r *http.Request) bool { + return true + }, + } + conn, err := upgrader.Upgrade(w, r, nil) + if err != nil { + t.Fatalf("failed to upgrade WebSocket connection: %v", err) + return + } + handler(t, conn, response) + })) +} + +// webSocketProxyHandler forwards WebSocket connections to the target server. +// +//nolint:errcheck //we can safely ignore errors checks here +func webSocketProxyHandler(targetURL string) http.HandlerFunc { + return func(w http.ResponseWriter, r *http.Request) { + defer r.Response.Body.Close() + //nolint:bodyclose // we can ignore the body close here + targetConn, _, err := websocket.DefaultDialer.Dial(targetURL, nil) + if err != nil { + http.Error(w, "failed to connect to backend WebSocket server", http.StatusBadGateway) + return + } + defer targetConn.Close() + + upgrader := websocket.Upgrader{ + CheckOrigin: func(r *http.Request) bool { + return true + }, + } + clientConn, err := upgrader.Upgrade(w, r, nil) + if err != nil { + http.Error(w, "failed to upgrade client connection", http.StatusInternalServerError) + return + } + defer clientConn.Close() + // forward messages between client and target server + go func() { + for { + messageType, message, err := targetConn.ReadMessage() + if err != nil { + break + } + clientConn.WriteMessage(messageType, message) + } + }() + for { + messageType, message, err := clientConn.ReadMessage() + if err != nil { + break + } + targetConn.WriteMessage(messageType, message) + } + } +} + +// newWebSocketProxyTestServer creates a proxy server forwarding WebSocket traffic. +func newWebSocketProxyTestServer(t *testing.T, handler WebSocketHandler, config map[string]interface{}, response []string) *httptest.Server { + backendServer := webSocketTestServer(t, handler, response) + config["url"] = "ws" + backendServer.URL[4:] + config["proxy_url"] = "ws" + backendServer.URL[4:] + return httptest.NewServer(webSocketProxyHandler(config["url"].(string))) +} diff --git a/x-pack/filebeat/input/streaming/testdata/certs/ca.crt b/x-pack/filebeat/input/streaming/testdata/certs/ca.crt new file mode 100644 index 000000000000..43e187f1367f --- /dev/null +++ b/x-pack/filebeat/input/streaming/testdata/certs/ca.crt @@ -0,0 +1,21 @@ +-----BEGIN CERTIFICATE----- +MIIDbTCCAlWgAwIBAgIUS/rm8sWDc2a+eD9L+q+9XQpBa5MwDQYJKoZIhvcNAQEL +BQAwRTELMAkGA1UEBhMCQVUxEzARBgNVBAgMClNvbWUtU3RhdGUxITAfBgNVBAoM +GEludGVybmV0IFdpZGdpdHMgUHR5IEx0ZDAgFw0yNDEyMDUxMjM4NThaGA8yMTI0 +MTExMTEyMzg1OFowRTELMAkGA1UEBhMCQVUxEzARBgNVBAgMClNvbWUtU3RhdGUx +ITAfBgNVBAoMGEludGVybmV0IFdpZGdpdHMgUHR5IEx0ZDCCASIwDQYJKoZIhvcN +AQEBBQADggEPADCCAQoCggEBALhEaFVqFuYwSwH4GHhMeqhilC+sWXKaQP8QmaH7 +HWRST8Ko6YTT9NixUL4Qs5OmzCQFavRN9qtEo4wtqCJBOEyXQG1wAHuLWIY+KOCB +twUg8fP+uYaYUOQOYNLkBz7SLlejuZYTyGxepIkc+UeJRcOE36anIPHpc2KSr3Hm +vKJxZUVpQEbJvQ7pe7+iLL4jSOfzpQNcV9S/bzTo6taZXuo+ryEPlshkU/ME5VCN +LFrU3AW2fzKW0Xa/skkW5izCiAU8KNEy84UQM6aZkJfFi9O394i97sGgYg+q36XL +sXbZ+sCXHI3CGx+pwOx0h7S8n7iJJ7BbmwM6QuLFF6bFYkkCAwEAAaNTMFEwHQYD +VR0OBBYEFEHtfvey8SdncMr7VDqA2YhtEiGYMB8GA1UdIwQYMBaAFEHtfvey8Sdn +cMr7VDqA2YhtEiGYMA8GA1UdEwEB/wQFMAMBAf8wDQYJKoZIhvcNAQELBQADggEB +AKFcAeh9yhIbkkxvXl6ebmLcj817NVjhpcvDZlKP2MVu+w/h70w+JwBktLUlZlXd +UNkKEWZyRvrdmY+YN6rwY/QI75N17bcmDWy6QnNlVJF0AJkBSdbKonCgHrZm7K25 +TOKpj0QF8l7k9wr5FWHHcBw/vFF9cGZ5TO4HbnI25N/cEKgdzZFEVA5Y/Rv7GIGU +COjJG20Cr2HIKvVYoyWvN6sL7+gbzUMyjvQyGMCT7YoIqscUfrUU+T46QaOLAKa3 +z91Obfmv6uTO/rsieoxVWVJ35GeHeNJkAPkr7Z1sWIrreJ/3WsecWuPPEDNDXiSV +5h0bTbbPOyEIe5ydEIbr5kA= +-----END CERTIFICATE----- diff --git a/x-pack/filebeat/input/streaming/testdata/certs/cert.pem b/x-pack/filebeat/input/streaming/testdata/certs/cert.pem new file mode 100644 index 000000000000..43e187f1367f --- /dev/null +++ b/x-pack/filebeat/input/streaming/testdata/certs/cert.pem @@ -0,0 +1,21 @@ +-----BEGIN CERTIFICATE----- +MIIDbTCCAlWgAwIBAgIUS/rm8sWDc2a+eD9L+q+9XQpBa5MwDQYJKoZIhvcNAQEL +BQAwRTELMAkGA1UEBhMCQVUxEzARBgNVBAgMClNvbWUtU3RhdGUxITAfBgNVBAoM +GEludGVybmV0IFdpZGdpdHMgUHR5IEx0ZDAgFw0yNDEyMDUxMjM4NThaGA8yMTI0 +MTExMTEyMzg1OFowRTELMAkGA1UEBhMCQVUxEzARBgNVBAgMClNvbWUtU3RhdGUx +ITAfBgNVBAoMGEludGVybmV0IFdpZGdpdHMgUHR5IEx0ZDCCASIwDQYJKoZIhvcN +AQEBBQADggEPADCCAQoCggEBALhEaFVqFuYwSwH4GHhMeqhilC+sWXKaQP8QmaH7 +HWRST8Ko6YTT9NixUL4Qs5OmzCQFavRN9qtEo4wtqCJBOEyXQG1wAHuLWIY+KOCB +twUg8fP+uYaYUOQOYNLkBz7SLlejuZYTyGxepIkc+UeJRcOE36anIPHpc2KSr3Hm +vKJxZUVpQEbJvQ7pe7+iLL4jSOfzpQNcV9S/bzTo6taZXuo+ryEPlshkU/ME5VCN +LFrU3AW2fzKW0Xa/skkW5izCiAU8KNEy84UQM6aZkJfFi9O394i97sGgYg+q36XL +sXbZ+sCXHI3CGx+pwOx0h7S8n7iJJ7BbmwM6QuLFF6bFYkkCAwEAAaNTMFEwHQYD +VR0OBBYEFEHtfvey8SdncMr7VDqA2YhtEiGYMB8GA1UdIwQYMBaAFEHtfvey8Sdn +cMr7VDqA2YhtEiGYMA8GA1UdEwEB/wQFMAMBAf8wDQYJKoZIhvcNAQELBQADggEB +AKFcAeh9yhIbkkxvXl6ebmLcj817NVjhpcvDZlKP2MVu+w/h70w+JwBktLUlZlXd +UNkKEWZyRvrdmY+YN6rwY/QI75N17bcmDWy6QnNlVJF0AJkBSdbKonCgHrZm7K25 +TOKpj0QF8l7k9wr5FWHHcBw/vFF9cGZ5TO4HbnI25N/cEKgdzZFEVA5Y/Rv7GIGU +COjJG20Cr2HIKvVYoyWvN6sL7+gbzUMyjvQyGMCT7YoIqscUfrUU+T46QaOLAKa3 +z91Obfmv6uTO/rsieoxVWVJ35GeHeNJkAPkr7Z1sWIrreJ/3WsecWuPPEDNDXiSV +5h0bTbbPOyEIe5ydEIbr5kA= +-----END CERTIFICATE----- diff --git a/x-pack/filebeat/input/streaming/testdata/certs/key.pem b/x-pack/filebeat/input/streaming/testdata/certs/key.pem new file mode 100644 index 000000000000..1b6ce6bade3c --- /dev/null +++ b/x-pack/filebeat/input/streaming/testdata/certs/key.pem @@ -0,0 +1,28 @@ +-----BEGIN PRIVATE KEY----- +MIIEvQIBADANBgkqhkiG9w0BAQEFAASCBKcwggSjAgEAAoIBAQC4RGhVahbmMEsB ++Bh4THqoYpQvrFlymkD/EJmh+x1kUk/CqOmE0/TYsVC+ELOTpswkBWr0TfarRKOM +LagiQThMl0BtcAB7i1iGPijggbcFIPHz/rmGmFDkDmDS5Ac+0i5Xo7mWE8hsXqSJ +HPlHiUXDhN+mpyDx6XNikq9x5ryicWVFaUBGyb0O6Xu/oiy+I0jn86UDXFfUv280 +6OrWmV7qPq8hD5bIZFPzBOVQjSxa1NwFtn8yltF2v7JJFuYswogFPCjRMvOFEDOm +mZCXxYvTt/eIve7BoGIPqt+ly7F22frAlxyNwhsfqcDsdIe0vJ+4iSewW5sDOkLi +xRemxWJJAgMBAAECggEAQprvf5hWaKQiKLcN2UYDvCPN3qGUv3kEb24HqmZDjIS4 +MeuuZQXcZgtJ3TnaP0+2UHro2x/nPqcT2tKSCLe8aurtLeGjOwT2XafQTL52clMj +Qgfb9cvOyXBtDS3BdLKyb5lNtvK1qn5XSPyBGpuC7RZ1ZR7aKLcyrvnIkwpNOwXW +zH5F6pI6HAUPfgYcHfIkQ5kuPCRcvfmv6m9XLYlmiQNkReQ2fWtFF6517R6FGtZu +Z8F0pFz8VtIGQoamX9vEwQhYqBK67msl9gnKjyH3ONckkSRMVagXrwx9F5o+NeRD +IgDFnjH1HgLCXmeCa7BN+eYfGMZ24xisItD7XBzGtQKBgQDlmEncIgpkmtXZSvXs +r5i7epJDDcxC8/ZObsn3zI01t4nmI9+phu7a4fAA+AUP7+HFVdi22JcHDkHZ5J1a +93t+Tcc4yzXk8FovaavRRvJNXv3WhHvgNpe1tvgyMUc8p9QpfbHuafVhQN2qWivh +nnEWagBoguiXaXEIFRXFK6dt5wKBgQDNdZYQ4/Am7HNjI2vqmMccZxuSufUX0xxM +LuDY8UAsPbgRN8wqfY67xCdMztax5y15gF9UPw0hHMlk4m2J4lsqCqgRRWXnTser +rNAseZ1j7MZY0cKACRxvXNtPKmmHKvYHUEZkADT/HrhfZWIce7KEXaxdoGTkssPd +9/WbahLITwKBgFBa2VbTDyIg0sGHK8UXu/O5tWEEfj3clpLi0YsJq05mmzvRyGDT +2dr/gnlEVLk8Mp9XKU7tRQZyJff1vGDvBuiwng4xiP5EZLv9VuYa14jeuyaOHbDe +SoCNthYTCySedHHFDTYtHXVZN3t8raj8RAYdOWFal78OZ0H15zWnzqR3AoGBAJne +mxFxM3RjFpNDftmFq3BpA6xiGdzK3OFtJjUykAXR/xzd9chImfGjGG+cZAt9/3+E +FWCpi7KltWoZbUGbRPz6WB3/JC8Tv9OhK5JzTdz9ARqZlRmAOUxpdVEXiUqScQjP +JLhVs1rw7dF7wvtj5DDfWmwP6B+iha+huM24pfJfAoGAUYeJQ1XqEx+0+b6xrtCm +qxPiiGnJSi4J9CGaZRMTG5qFSQ5jCaWTJSWdiZJgyBMnmQsiuPacefAg91z/NjJC +xM0/sKLe/yPWP1UlwrCl1MDjMwIl/qtWiKXYXpY1qcOONLCFc6OASd1cTOtX/7Km +2g49JWZEY71f7DxLdcWfqWM= +-----END PRIVATE KEY----- diff --git a/x-pack/filebeat/input/streaming/websocket.go b/x-pack/filebeat/input/streaming/websocket.go index 0c8de94f5ad3..8a78757f0e96 100644 --- a/x-pack/filebeat/input/streaming/websocket.go +++ b/x-pack/filebeat/input/streaming/websocket.go @@ -7,6 +7,7 @@ package streaming import ( "bytes" "context" + "crypto/tls" "errors" "fmt" "io" @@ -14,6 +15,7 @@ import ( "math/rand/v2" "net" "net/http" + "net/url" "strings" "time" @@ -22,6 +24,8 @@ import ( inputcursor "github.com/elastic/beats/v7/filebeat/input/v2/input-cursor" "github.com/elastic/elastic-agent-libs/logp" + "github.com/elastic/elastic-agent-libs/transport/httpcommon" + "github.com/elastic/elastic-agent-libs/transport/tlscommon" ) type websocketStream struct { @@ -220,14 +224,18 @@ func connectWebSocket(ctx context.Context, cfg config, url string, log *logp.Log var response *http.Response var err error headers := formHeader(cfg) - + dialer, err := createWebSocketDialer(cfg) + if err != nil { + return nil, nil, err + } if cfg.Retry != nil { retryConfig := cfg.Retry for attempt := 1; attempt <= retryConfig.MaxAttempts; attempt++ { - conn, response, err = websocket.DefaultDialer.DialContext(ctx, url, headers) + conn, response, err = dialer.DialContext(ctx, url, headers) if err == nil { return conn, response, nil } + //nolint:errorlint // it will never be a wrapped error at this point if err == websocket.ErrBadHandshake { log.Errorf("attempt %d: webSocket connection failed with bad handshake (status %d) retrying...\n", attempt, response.StatusCode) continue @@ -239,7 +247,7 @@ func connectWebSocket(ctx context.Context, cfg config, url string, log *logp.Log return nil, nil, fmt.Errorf("failed to establish WebSocket connection after %d attempts with error %w", retryConfig.MaxAttempts, err) } - return websocket.DefaultDialer.DialContext(ctx, url, headers) + return dialer.DialContext(ctx, url, headers) } // calculateWaitTime calculates the wait time for the next attempt based on the exponential backoff algorithm. @@ -269,3 +277,42 @@ func (s *websocketStream) Close() error { s.metrics.Close() return nil } + +func createWebSocketDialer(cfg config) (*websocket.Dialer, error) { + var tlsConfig *tls.Config + dialer := &websocket.Dialer{ + Proxy: http.ProxyFromEnvironment, + } + + // load proxy configuration if available + if cfg.Transport.Proxy.URL != nil { + var proxy func(*http.Request) (*url.URL, error) + proxyURL, err := httpcommon.NewProxyURIFromString(cfg.Transport.Proxy.URL.String()) + if err != nil { + return nil, fmt.Errorf("failed to parse proxy URL: %w", err) + } + // create a custom HTTP Transport with proxy configuration + proxyTransport := &http.Transport{ + Proxy: http.ProxyURL(proxyURL.URI()), + ProxyConnectHeader: cfg.Transport.Proxy.Headers.Headers(), + DialContext: (&net.Dialer{ + Timeout: cfg.Transport.Timeout, + }).DialContext, + } + dialer.NetDialContext = func(ctx context.Context, network, addr string) (net.Conn, error) { + return proxyTransport.DialContext(ctx, network, addr) + } + dialer.Proxy = proxy + } + // load TLS config if available + if cfg.Transport.TLS != nil { + TLSConfig, err := tlscommon.LoadTLSConfig(cfg.Transport.TLS) + if err != nil { + return nil, fmt.Errorf("failed to load TLS config: %w", err) + } + tlsConfig = TLSConfig.ToConfig() + dialer.TLSClientConfig = tlsConfig + } + + return dialer, nil +} From 002a22024daa5db9135dcd3877348e8f4861e1c0 Mon Sep 17 00:00:00 2001 From: ShourieG Date: Wed, 11 Dec 2024 12:02:15 +0530 Subject: [PATCH 36/48] [filebeat][gcs] - Removed bucket_timeout config option and replaced bucket context with parent program context (#41970) --- CHANGELOG.next.asciidoc | 1 + .../filebeat/docs/inputs/input-gcs.asciidoc | 51 ++++++------------- x-pack/filebeat/input/gcs/config.go | 12 ++--- x-pack/filebeat/input/gcs/input.go | 4 -- x-pack/filebeat/input/gcs/input_stateless.go | 1 - x-pack/filebeat/input/gcs/input_test.go | 3 -- x-pack/filebeat/input/gcs/job.go | 4 +- x-pack/filebeat/input/gcs/types.go | 1 - 8 files changed, 22 insertions(+), 55 deletions(-) diff --git a/CHANGELOG.next.asciidoc b/CHANGELOG.next.asciidoc index dd4f19be3350..9c0fbc06447e 100644 --- a/CHANGELOG.next.asciidoc +++ b/CHANGELOG.next.asciidoc @@ -451,6 +451,7 @@ https://github.com/elastic/beats/compare/v8.8.1\...main[Check the HEAD diff] *Filebeat* +- Removed `bucket_timeout` config option for GCS input and replaced bucket context with parent program context. {issue}41107[41107] {pull}41970[41970] *Heartbeat* diff --git a/x-pack/filebeat/docs/inputs/input-gcs.asciidoc b/x-pack/filebeat/docs/inputs/input-gcs.asciidoc index d85a7393440e..a2de572bce03 100644 --- a/x-pack/filebeat/docs/inputs/input-gcs.asciidoc +++ b/x-pack/filebeat/docs/inputs/input-gcs.asciidoc @@ -23,6 +23,8 @@ The input can be configured to work with and without polling, though if polling 3. If any major error occurs which stops the main thread, the logs will be appropriately generated, describing said error. +**Config Option Removal Notice** : The `bucket_timeout` config option has been removed from the google cloud storage input. The intention behind this removal is to simplify the configuration and to make it more user friendly. The `bucket_timeout` option was confusing and had the potential to let users malconfigure the input, which could lead to unexpected behavior. The input now uses a more robust and efficient way to handle the bucket timeout internally. + [id="supported-types-gcs"] NOTE: Currently only `JSON` and `NDJSON` are supported object/file formats. Objects/files may be also be gzip compressed. "JSON credential keys" and "credential files" are supported authentication types. @@ -46,24 +48,22 @@ filebeat.inputs: max_workers: 3 poll: true poll_interval: 15s - bucket_timeout: 60s - name: gcs-test-old max_workers: 3 poll: true poll_interval: 10s - bucket_timeout: 30s ---- *Explanation :* This `configuration` given above describes a basic gcs config having two buckets named `gcs-test-new` and `gcs-test-old`. -Each of these buckets have their own attributes such as `name`, `max_workers`, `poll`, `poll_interval` and `bucket_timeout`. These attributes have detailed explanations +Each of these buckets have their own attributes such as `name`, `max_workers`, `poll` and `poll_interval`. These attributes have detailed explanations given <>. For now lets try to understand how this config works. For google cloud storage input to identify the files it needs to read and process, it will require the bucket names to be specified. We can have as -many buckets as we deem fit. We are also able to configure the attributes `max_workers`, `poll`, `poll_interval` and `bucket_timeout` at the root level, which will +many buckets as we deem fit. We are also able to configure the attributes `max_workers`, `poll` and `poll_interval` at the root level, which will then be applied to all buckets which do not specify any of these attributes explicitly. -NOTE: If the attributes `max_workers`, `poll`, `poll_interval` and `bucket_timeout` are specified at the root level, these can still be overridden at the bucket level with +NOTE: If the attributes `max_workers`, `poll` and `poll_interval` are specified at the root level, these can still be overridden at the bucket level with different values, thus offering extensive flexibility and customization. Examples <> show this behavior. On receiving this config the google cloud storage input will connect to the service and retrieve a `Storage Client` using the given `bucket_name` and @@ -71,7 +71,7 @@ On receiving this config the google cloud storage input will connect to the serv which will in turn use the `max_workers` value to initialize an in-memory worker pool (thread pool) with `3` `workers` available. Basically that equates to two instances of a worker pool, one per bucket, each having 3 workers. These `workers` will be responsible for performing `jobs` that process a file (in this case read and output the contents of a file). NOTE: The scheduler is responsible for scheduling jobs, and uses the `maximum available workers` in the pool, at each iteration, to decide the number of files to retrieve and -process. This keeps work distribution efficient. The scheduler uses `poll_interval` attribute value to decide how long to wait after each iteration. The `bucket_timeout` value is used to timeout calls to the bucket list api if it exceeds the given value. Each iteration consists of processing a certain number of files, decided by the `maximum available workers` value. +process. This keeps work distribution efficient. The scheduler uses `poll_interval` attribute value to decide how long to wait after each iteration. Each iteration consists of processing a certain number of files, decided by the `maximum available workers` value. *A Sample Response :-* ["source","json"] @@ -156,15 +156,14 @@ Now let's explore the configuration attributes a bit more elaborately. 3. <> 4. <> 5. <> - 6. <> - 7. <> - 8. <> - 9. <> - 10. <> - 11. <> - 12. <> - 13. <> - 14. <> + 6. <> + 7. <> + 8. <> + 9. <> + 10. <> + 11. <> + 12. <> + 13. <> [id="attrib-project-id"] @@ -195,9 +194,7 @@ specified, then the one that occurs first in the configuration will be used. [float] ==== `buckets` -This attribute contains the details about a specific bucket like `name`, `max_workers`, `poll`, `poll_interval` and `bucket_timeout`. The attribute `name` is specific to a -bucket as it describes the bucket name, while the fields `max_workers`, `poll`, `poll_interval` and `bucket_timeout` can exist both at the bucket level and the root level. -This attribute is internally represented as an array, so we can add as many buckets as we require. +This attribute contains the details about a specific bucket like `name`, `max_workers`, `poll` and `poll_interval`. The attribute `name` is specific to a bucket as it describes the bucket name, while the fields `max_workers`, `poll` and `poll_interval` can exist both at the bucket level and the root level. This attribute is internally represented as an array, so we can add as many buckets as we require. [id="attrib-bucket-name"] [float] @@ -205,14 +202,6 @@ This attribute is internally represented as an array, so we can add as many buck This is a specific subfield of a bucket. It specifies the bucket name. -[id="attrib-bucket-timeout"] -[float] -==== `bucket_timeout` - -This attribute defines the maximum amount of time after which a bucket operation will give and stop if no response is recieved (example: reading a file / listing a file). -It can be defined in the following formats : `{{x}}s`, `{{x}}m`, `{{x}}h`, here `s = seconds`, `m = minutes` and `h = hours`. The value `{{x}}` can be anything we wish. -If no value is specified for this, by default its initialized to `120 seconds`. This attribute can be specified both at the root level of the configuration as well at the bucket level. The bucket level values will always take priority and override the root level values if both are specified. The value of `bucket_timeout` that should be used depends on the size of the files and the network speed. If the timeout is too low, the input will not be able to read the file completely and `context_deadline_exceeded` errors will be seen in the logs. If the timeout is too high, the input will wait for a long time for the file to be read, which can cause the input to be slow. The ratio between the `bucket_timeout` and `poll_interval` should be considered while setting both the values. A low `poll_interval` and a very high `bucket_timeout` can cause resource utilization issues as schedule ops will be spawned every poll iteration. If previous poll ops are still running, this could result in concurrently running ops and so could cause a bottleneck over time. - [id="attrib-max_workers-gcs"] [float] ==== `max_workers` @@ -237,9 +226,7 @@ This attribute defines the maximum amount of time after which the internal sched defined in the following formats : `{{x}}s`, `{{x}}m`, `{{x}}h`, here `s = seconds`, `m = minutes` and `h = hours`. The value `{{x}}` can be anything we wish. Example : `10s` would mean we would like the polling to occur every 10 seconds. If no value is specified for this, by default its initialized to `5 minutes`. This attribute can be specified both at the root level of the configuration as well at the bucket level. The bucket level values will always take priority -and override the root level values if both are specified. The `poll_interval` should be set to a value that is equal to the `bucket_timeout` value. This would ensure that another schedule operation is not started before the current buckets have all been processed. If the `poll_interval` is set to a value that is less than the `bucket_timeout`, then the input will start another schedule operation before the current one has finished, which can cause a bottleneck over time. Having a lower `poll_interval` can make the input faster at the cost of more resource utilization. - -NOTE: Some edge case scenarios could require different values for `poll_interval` and `bucket_timeout`. For example, if the files are very large and the network speed is slow, then the `bucket_timeout` value should be set to a higher value than the `poll_interval`. This would ensure that polling operation does not wait too long for the files to be read and moves to the next iteration while the current one is still being processed. This would ensure a higher throughput and better resource utilization. +and override the root level values if both are specified. Having a lower `poll_interval` can make the input faster at the cost of more resource utilization. [id="attrib-parse_json"] [float] @@ -322,7 +309,6 @@ filebeat.inputs: max_workers: 3 poll: true poll_interval: 15s - bucket_timeout: 60s file_selectors: - regex: '/Monitoring/' - regex: 'docs/' @@ -368,7 +354,6 @@ filebeat.inputs: max_workers: 3 poll: true poll_interval: 15s - bucket_timeout: 60s expand_event_list_from_field: Records ---- @@ -392,7 +377,6 @@ filebeat.inputs: max_workers: 3 poll: true poll_interval: 15s - bucket_timeout: 60s timestamp_epoch: 1630444800 ---- @@ -432,11 +416,8 @@ filebeat.inputs: max_workers: 3 poll: true poll_interval: 11m - bucket_timeout: 10m ---- -When configuring the `retry` attribute, the user should consider the `bucket_timeout` value. The `retry` attribute should be configured in such a way that the retries are completed within the `bucket_timeout` window. If the `retry` attribute is configured in such a way that the retries are not completed successfully within the `bucket_timeout` window, the input will suffer a `context timeout` for that specific object/file which it was retrying. This can cause gaps in ingested data to pile up over time. - [id="bucket-overrides"] *The sample configs below will explain the bucket level overriding of attributes a bit further :-* diff --git a/x-pack/filebeat/input/gcs/config.go b/x-pack/filebeat/input/gcs/config.go index 9a9f6dceadd4..3c8f2d02a7c7 100644 --- a/x-pack/filebeat/input/gcs/config.go +++ b/x-pack/filebeat/input/gcs/config.go @@ -36,8 +36,6 @@ type config struct { // ParseJSON - Informs the publisher whether to parse & objectify json data or not. By default this is set to // false, since it can get expensive dealing with highly nested json data. ParseJSON bool `config:"parse_json"` - // BucketTimeOut - Defines the maximum time that the sdk will wait for a bucket api response before timing out. - BucketTimeOut time.Duration `config:"bucket_timeout"` // Buckets - Defines a list of buckets that will be polled for objects. Buckets []bucket `config:"buckets" validate:"required"` // FileSelectors - Defines a list of regex patterns that can be used to filter out objects from the bucket. @@ -58,7 +56,6 @@ type config struct { type bucket struct { Name string `config:"name" validate:"required"` MaxWorkers *int `config:"max_workers" validate:"max=5000"` - BucketTimeOut *time.Duration `config:"bucket_timeout"` Poll *bool `config:"poll"` PollInterval *time.Duration `config:"poll_interval"` ParseJSON *bool `config:"parse_json"` @@ -136,11 +133,10 @@ func (c authConfig) Validate() error { // defaultConfig returns the default configuration for the input func defaultConfig() config { return config{ - MaxWorkers: 1, - Poll: true, - PollInterval: 5 * time.Minute, - BucketTimeOut: 120 * time.Second, - ParseJSON: false, + MaxWorkers: 1, + Poll: true, + PollInterval: 5 * time.Minute, + ParseJSON: false, Retry: retryConfig{ MaxAttempts: 3, InitialBackOffDuration: time.Second, diff --git a/x-pack/filebeat/input/gcs/input.go b/x-pack/filebeat/input/gcs/input.go index 1d6bff8b857a..77580f70e401 100644 --- a/x-pack/filebeat/input/gcs/input.go +++ b/x-pack/filebeat/input/gcs/input.go @@ -63,7 +63,6 @@ func configure(cfg *conf.C) ([]cursor.Source, cursor.Input, error) { sources = append(sources, &Source{ ProjectId: config.ProjectId, BucketName: bucket.Name, - BucketTimeOut: *bucket.BucketTimeOut, MaxWorkers: *bucket.MaxWorkers, Poll: *bucket.Poll, PollInterval: *bucket.PollInterval, @@ -93,9 +92,6 @@ func tryOverrideOrDefault(cfg config, b bucket) bucket { if b.ParseJSON == nil { b.ParseJSON = &cfg.ParseJSON } - if b.BucketTimeOut == nil { - b.BucketTimeOut = &cfg.BucketTimeOut - } if b.TimeStampEpoch == nil { b.TimeStampEpoch = cfg.TimeStampEpoch } diff --git a/x-pack/filebeat/input/gcs/input_stateless.go b/x-pack/filebeat/input/gcs/input_stateless.go index b6901f0df25f..bceb7dffb54d 100644 --- a/x-pack/filebeat/input/gcs/input_stateless.go +++ b/x-pack/filebeat/input/gcs/input_stateless.go @@ -54,7 +54,6 @@ func (in *statelessInput) Run(inputCtx v2.Context, publisher stateless.Publisher source = &Source{ ProjectId: in.config.ProjectId, BucketName: bucket.Name, - BucketTimeOut: *bucket.BucketTimeOut, MaxWorkers: *bucket.MaxWorkers, Poll: *bucket.Poll, PollInterval: *bucket.PollInterval, diff --git a/x-pack/filebeat/input/gcs/input_test.go b/x-pack/filebeat/input/gcs/input_test.go index 345c7c579096..8ff0576bdf5e 100644 --- a/x-pack/filebeat/input/gcs/input_test.go +++ b/x-pack/filebeat/input/gcs/input_test.go @@ -528,7 +528,6 @@ func Test_StorageClient(t *testing.T) { "max_workers": 1, "poll": true, "poll_interval": "1m", - "bucket_timeout": "1m", "buckets": []map[string]interface{}{ { "name": "gcs-test-new", @@ -550,7 +549,6 @@ func Test_StorageClient(t *testing.T) { "max_workers": 1, "poll": true, "poll_interval": "10s", - "bucket_timeout": "10s", "retry": map[string]interface{}{ "max_attempts": 5, "initial_backoff_duration": "1s", @@ -578,7 +576,6 @@ func Test_StorageClient(t *testing.T) { "max_workers": 1, "poll": true, "poll_interval": "10s", - "bucket_timeout": "10s", "retry": map[string]interface{}{ "max_attempts": 5, "initial_backoff_duration": "1s", diff --git a/x-pack/filebeat/input/gcs/job.go b/x-pack/filebeat/input/gcs/job.go index 114200021599..6de97561b3c0 100644 --- a/x-pack/filebeat/input/gcs/job.go +++ b/x-pack/filebeat/input/gcs/job.go @@ -147,10 +147,8 @@ func (j *job) Timestamp() time.Time { } func (j *job) processAndPublishData(ctx context.Context, id string) error { - ctxWithTimeout, cancel := context.WithTimeout(ctx, j.src.BucketTimeOut) - defer cancel() obj := j.bucket.Object(j.object.Name) - reader, err := obj.NewReader(ctxWithTimeout) + reader, err := obj.NewReader(ctx) if err != nil { return fmt.Errorf("failed to open reader for object: %s, with error: %w", j.object.Name, err) } diff --git a/x-pack/filebeat/input/gcs/types.go b/x-pack/filebeat/input/gcs/types.go index 82fb737cdb65..72bf98e08e51 100644 --- a/x-pack/filebeat/input/gcs/types.go +++ b/x-pack/filebeat/input/gcs/types.go @@ -12,7 +12,6 @@ import ( // Source, it is the cursor source type Source struct { BucketName string - BucketTimeOut time.Duration ProjectId string MaxWorkers int Poll bool From fb93eee6c66e000efe90bab628b58ef7687f9b9a Mon Sep 17 00:00:00 2001 From: Anderson Queiroz Date: Wed, 11 Dec 2024 07:34:18 +0100 Subject: [PATCH 37/48] Remove functionbeat (#41506) * Remove functionbeat * Add changelog entry for functionbeat removal --------- Co-authored-by: julienlind --- .buildkite/packaging.pipeline.yml | 4 +- .../workflows/check-xpack-functionbeat.yml | 28 - .../updatecli.d/bump-golang-7.17.yml | 10 - .github/workflows/updatecli.d/bump-golang.yml | 10 - .gitignore | 3 - CHANGELOG.next.asciidoc | 2 + Makefile | 2 +- NOTICE.txt | 986 +- README.md | 2 - dev-tools/cmd/update_go/update_go_version.go | 1 - docs/devguide/documentation.asciidoc | 3 +- go.mod | 9 +- go.sum | 20 +- libbeat/docs/command-reference.asciidoc | 140 +- libbeat/docs/overview.asciidoc | 1 - libbeat/publisher/pipeline/sync_client.go | 106 - .../publisher/pipeline/sync_client_test.go | 132 - x-pack/functionbeat/.gitignore | 10 - x-pack/functionbeat/Dockerfile | 25 - x-pack/functionbeat/Jenkinsfile.yml | 100 - x-pack/functionbeat/Makefile | 10 - .../_meta/config/beat.reference.yml.tmpl | 297 - .../functionbeat/_meta/config/beat.yml.tmpl | 253 - x-pack/functionbeat/_meta/fields.yml | 4 - x-pack/functionbeat/config/config.go | 143 - x-pack/functionbeat/config/config_test.go | 128 - x-pack/functionbeat/conftest.py | 5 - .../dev-tools/packaging/packages.yml | 100 - x-pack/functionbeat/docker-compose.yml | 28 - .../docs/config-options-aws.asciidoc | 219 - .../docs/configuring-howto.asciidoc | 66 - x-pack/functionbeat/docs/deploying.asciidoc | 113 - .../export-cloudformation-template.asciidoc | 27 - .../docs/faq-resource-limit.asciidoc | 55 - x-pack/functionbeat/docs/faq.asciidoc | 23 - x-pack/functionbeat/docs/fields.asciidoc | 15676 ---------------- x-pack/functionbeat/docs/filtering.asciidoc | 30 - .../docs/general-options.asciidoc | 13 - .../docs/getting-started.asciidoc | 167 - x-pack/functionbeat/docs/howto/howto.asciidoc | 42 - .../docs/iam-permissions.asciidoc | 134 - .../docs/images/coordinate-map.png | Bin 370029 -> 0 bytes .../diagram-functionbeat-architecture.svg | 568 - .../functionbeat-pipeline-cloudwatchlogs.png | Bin 82236 -> 0 bytes .../docs/images/functionbeat-pipeline-sqs.png | Bin 81731 -> 0 bytes x-pack/functionbeat/docs/index.asciidoc | 64 - x-pack/functionbeat/docs/overview.asciidoc | 99 - x-pack/functionbeat/docs/page_header.html | 3 - .../docs/setting-up-running.asciidoc | 45 - .../credentials-aws-widget.asciidoc | 58 - .../docs/tab-widgets/credentials-aws.asciidoc | 26 - .../tab-widgets/deploy-aws-widget.asciidoc | 58 - .../docs/tab-widgets/deploy-aws.asciidoc | 19 - .../docs/troubleshooting.asciidoc | 43 - .../function/beater/functionbeat.go | 185 - .../function/beater/proccessors_test.go | 124 - .../function/beater/processors.go | 38 - x-pack/functionbeat/function/cmd/root.go | 54 - .../functionbeat/function/core/coordinator.go | 98 - .../function/core/coordinator_test.go | 58 - x-pack/functionbeat/function/provider/cli.go | 32 - .../function/provider/default_provider.go | 112 - .../functionbeat/function/provider/feature.go | 64 - .../function/provider/feature_test.go | 51 - .../function/provider/provider.go | 133 - .../function/provider/provider_test.go | 74 - .../function/provider/registry.go | 217 - .../function/provider/registry_test.go | 274 - .../function/provider/template.go | 19 - .../function/telemetry/telemetry.go | 37 - .../functionbeat/functionbeat.reference.yml | 1573 -- x-pack/functionbeat/functionbeat.yml | 416 - x-pack/functionbeat/include/feature.go | 16 - x-pack/functionbeat/include/fields.go | 23 - x-pack/functionbeat/magefile.go | 234 - x-pack/functionbeat/main.go | 19 - x-pack/functionbeat/main_test.go | 40 - x-pack/functionbeat/make.bat | 11 - x-pack/functionbeat/manager/aws/aws.go | 33 - .../functionbeat/manager/aws/cli_manager.go | 240 - .../manager/aws/cli_manager_test.go | 38 - .../manager/aws/cloudformation_interface.go | 24 - .../manager/aws/event_stack_poller.go | 157 - .../manager/aws/event_stack_poller_test.go | 341 - .../manager/aws/op_cloudformation.go | 110 - .../manager/aws/op_cloudformation_test.go | 211 - .../manager/aws/op_delete_cloudformation.go | 63 - .../manager/aws/op_delete_file_bucket.go | 52 - .../manager/aws/op_ensure_bucket.go | 61 - .../manager/aws/op_update_cloudformation.go | 68 - .../manager/aws/op_upload_to_bucket.go | 68 - .../manager/aws/op_wait_cloud_formation.go | 145 - .../functionbeat/manager/aws/policies_test.go | 71 - .../functionbeat/manager/aws/stack_context.go | 24 - .../manager/aws/template_builder.go | 331 - .../manager/beater/functionbeat.go | 58 - .../functionbeat/manager/cmd/cli_handler.go | 162 - .../manager/cmd/cli_handler_test.go | 161 - .../functionbeat/manager/cmd/provider_cmd.go | 142 - x-pack/functionbeat/manager/cmd/root.go | 50 - .../manager/core/bundle/bundle.go | 243 - .../manager/core/bundle/bundle_test.go | 150 - .../manager/core/bundle/testdata/lipsum.txt | 1 - x-pack/functionbeat/manager/core/makezip.go | 115 - .../functionbeat/manager/executor/executor.go | 112 - .../manager/executor/executor_test.go | 181 - .../provider/aws/aws/api_gateway_proxy.go | 96 - .../aws/aws/api_gateway_proxy_test.go | 92 - .../provider/aws/aws/cloudwatch_kinesis.go | 117 - .../provider/aws/aws/cloudwatch_logs.go | 230 - .../provider/aws/aws/cloudwatch_logs_test.go | 153 - .../functionbeat/provider/aws/aws/config.go | 186 - .../provider/aws/aws/config_test.go | 135 - .../functionbeat/provider/aws/aws/kinesis.go | 226 - .../provider/aws/aws/kinesis_test.go | 302 - x-pack/functionbeat/provider/aws/aws/sqs.go | 164 - .../functionbeat/provider/aws/aws/sqs_test.go | 67 - .../aws/aws/transformer/transformer.go | 234 - .../aws/aws/transformer/transformer_test.go | 403 - x-pack/functionbeat/provider/aws/cmd/root.go | 29 - .../provider/aws/include/feature.go | 37 - x-pack/functionbeat/provider/aws/main.go | 18 - x-pack/functionbeat/provider/aws/main_test.go | 35 - .../functionbeat/provider/local/cmd/root.go | 20 - .../provider/local/include/feature.go | 14 - .../provider/local/local/local.go | 103 - x-pack/functionbeat/provider/local/main.go | 18 - .../functionbeat/provider/local/main_test.go | 35 - x-pack/functionbeat/scripts/mage/config.go | 23 - x-pack/functionbeat/scripts/mage/providers.go | 55 - x-pack/functionbeat/scripts/mage/update.go | 48 - .../tests/system/config/functionbeat.yml.j2 | 101 - .../functionbeat/tests/system/functionbeat.py | 12 - .../tests/system/requirements.txt | 1 - x-pack/functionbeat/tests/system/test_base.py | 118 - .../docs/aws-credentials-config.asciidoc | 4 - 136 files changed, 76 insertions(+), 30424 deletions(-) delete mode 100644 .github/workflows/check-xpack-functionbeat.yml delete mode 100644 libbeat/publisher/pipeline/sync_client.go delete mode 100644 libbeat/publisher/pipeline/sync_client_test.go delete mode 100644 x-pack/functionbeat/.gitignore delete mode 100644 x-pack/functionbeat/Dockerfile delete mode 100644 x-pack/functionbeat/Jenkinsfile.yml delete mode 100644 x-pack/functionbeat/Makefile delete mode 100644 x-pack/functionbeat/_meta/config/beat.reference.yml.tmpl delete mode 100644 x-pack/functionbeat/_meta/config/beat.yml.tmpl delete mode 100644 x-pack/functionbeat/_meta/fields.yml delete mode 100644 x-pack/functionbeat/config/config.go delete mode 100644 x-pack/functionbeat/config/config_test.go delete mode 100644 x-pack/functionbeat/conftest.py delete mode 100644 x-pack/functionbeat/dev-tools/packaging/packages.yml delete mode 100644 x-pack/functionbeat/docker-compose.yml delete mode 100644 x-pack/functionbeat/docs/config-options-aws.asciidoc delete mode 100644 x-pack/functionbeat/docs/configuring-howto.asciidoc delete mode 100644 x-pack/functionbeat/docs/deploying.asciidoc delete mode 100644 x-pack/functionbeat/docs/export-cloudformation-template.asciidoc delete mode 100644 x-pack/functionbeat/docs/faq-resource-limit.asciidoc delete mode 100644 x-pack/functionbeat/docs/faq.asciidoc delete mode 100644 x-pack/functionbeat/docs/fields.asciidoc delete mode 100644 x-pack/functionbeat/docs/filtering.asciidoc delete mode 100644 x-pack/functionbeat/docs/general-options.asciidoc delete mode 100644 x-pack/functionbeat/docs/getting-started.asciidoc delete mode 100644 x-pack/functionbeat/docs/howto/howto.asciidoc delete mode 100644 x-pack/functionbeat/docs/iam-permissions.asciidoc delete mode 100644 x-pack/functionbeat/docs/images/coordinate-map.png delete mode 100644 x-pack/functionbeat/docs/images/diagram-functionbeat-architecture.svg delete mode 100644 x-pack/functionbeat/docs/images/functionbeat-pipeline-cloudwatchlogs.png delete mode 100644 x-pack/functionbeat/docs/images/functionbeat-pipeline-sqs.png delete mode 100644 x-pack/functionbeat/docs/index.asciidoc delete mode 100644 x-pack/functionbeat/docs/overview.asciidoc delete mode 100644 x-pack/functionbeat/docs/page_header.html delete mode 100644 x-pack/functionbeat/docs/setting-up-running.asciidoc delete mode 100644 x-pack/functionbeat/docs/tab-widgets/credentials-aws-widget.asciidoc delete mode 100644 x-pack/functionbeat/docs/tab-widgets/credentials-aws.asciidoc delete mode 100644 x-pack/functionbeat/docs/tab-widgets/deploy-aws-widget.asciidoc delete mode 100644 x-pack/functionbeat/docs/tab-widgets/deploy-aws.asciidoc delete mode 100644 x-pack/functionbeat/docs/troubleshooting.asciidoc delete mode 100644 x-pack/functionbeat/function/beater/functionbeat.go delete mode 100644 x-pack/functionbeat/function/beater/proccessors_test.go delete mode 100644 x-pack/functionbeat/function/beater/processors.go delete mode 100644 x-pack/functionbeat/function/cmd/root.go delete mode 100644 x-pack/functionbeat/function/core/coordinator.go delete mode 100644 x-pack/functionbeat/function/core/coordinator_test.go delete mode 100644 x-pack/functionbeat/function/provider/cli.go delete mode 100644 x-pack/functionbeat/function/provider/default_provider.go delete mode 100644 x-pack/functionbeat/function/provider/feature.go delete mode 100644 x-pack/functionbeat/function/provider/feature_test.go delete mode 100644 x-pack/functionbeat/function/provider/provider.go delete mode 100644 x-pack/functionbeat/function/provider/provider_test.go delete mode 100644 x-pack/functionbeat/function/provider/registry.go delete mode 100644 x-pack/functionbeat/function/provider/registry_test.go delete mode 100644 x-pack/functionbeat/function/provider/template.go delete mode 100644 x-pack/functionbeat/function/telemetry/telemetry.go delete mode 100644 x-pack/functionbeat/functionbeat.reference.yml delete mode 100644 x-pack/functionbeat/functionbeat.yml delete mode 100644 x-pack/functionbeat/include/feature.go delete mode 100644 x-pack/functionbeat/include/fields.go delete mode 100644 x-pack/functionbeat/magefile.go delete mode 100644 x-pack/functionbeat/main.go delete mode 100644 x-pack/functionbeat/main_test.go delete mode 100644 x-pack/functionbeat/make.bat delete mode 100644 x-pack/functionbeat/manager/aws/aws.go delete mode 100644 x-pack/functionbeat/manager/aws/cli_manager.go delete mode 100644 x-pack/functionbeat/manager/aws/cli_manager_test.go delete mode 100644 x-pack/functionbeat/manager/aws/cloudformation_interface.go delete mode 100644 x-pack/functionbeat/manager/aws/event_stack_poller.go delete mode 100644 x-pack/functionbeat/manager/aws/event_stack_poller_test.go delete mode 100644 x-pack/functionbeat/manager/aws/op_cloudformation.go delete mode 100644 x-pack/functionbeat/manager/aws/op_cloudformation_test.go delete mode 100644 x-pack/functionbeat/manager/aws/op_delete_cloudformation.go delete mode 100644 x-pack/functionbeat/manager/aws/op_delete_file_bucket.go delete mode 100644 x-pack/functionbeat/manager/aws/op_ensure_bucket.go delete mode 100644 x-pack/functionbeat/manager/aws/op_update_cloudformation.go delete mode 100644 x-pack/functionbeat/manager/aws/op_upload_to_bucket.go delete mode 100644 x-pack/functionbeat/manager/aws/op_wait_cloud_formation.go delete mode 100644 x-pack/functionbeat/manager/aws/policies_test.go delete mode 100644 x-pack/functionbeat/manager/aws/stack_context.go delete mode 100644 x-pack/functionbeat/manager/aws/template_builder.go delete mode 100644 x-pack/functionbeat/manager/beater/functionbeat.go delete mode 100644 x-pack/functionbeat/manager/cmd/cli_handler.go delete mode 100644 x-pack/functionbeat/manager/cmd/cli_handler_test.go delete mode 100644 x-pack/functionbeat/manager/cmd/provider_cmd.go delete mode 100644 x-pack/functionbeat/manager/cmd/root.go delete mode 100644 x-pack/functionbeat/manager/core/bundle/bundle.go delete mode 100644 x-pack/functionbeat/manager/core/bundle/bundle_test.go delete mode 100644 x-pack/functionbeat/manager/core/bundle/testdata/lipsum.txt delete mode 100644 x-pack/functionbeat/manager/core/makezip.go delete mode 100644 x-pack/functionbeat/manager/executor/executor.go delete mode 100644 x-pack/functionbeat/manager/executor/executor_test.go delete mode 100644 x-pack/functionbeat/provider/aws/aws/api_gateway_proxy.go delete mode 100644 x-pack/functionbeat/provider/aws/aws/api_gateway_proxy_test.go delete mode 100644 x-pack/functionbeat/provider/aws/aws/cloudwatch_kinesis.go delete mode 100644 x-pack/functionbeat/provider/aws/aws/cloudwatch_logs.go delete mode 100644 x-pack/functionbeat/provider/aws/aws/cloudwatch_logs_test.go delete mode 100644 x-pack/functionbeat/provider/aws/aws/config.go delete mode 100644 x-pack/functionbeat/provider/aws/aws/config_test.go delete mode 100644 x-pack/functionbeat/provider/aws/aws/kinesis.go delete mode 100644 x-pack/functionbeat/provider/aws/aws/kinesis_test.go delete mode 100644 x-pack/functionbeat/provider/aws/aws/sqs.go delete mode 100644 x-pack/functionbeat/provider/aws/aws/sqs_test.go delete mode 100644 x-pack/functionbeat/provider/aws/aws/transformer/transformer.go delete mode 100644 x-pack/functionbeat/provider/aws/aws/transformer/transformer_test.go delete mode 100644 x-pack/functionbeat/provider/aws/cmd/root.go delete mode 100644 x-pack/functionbeat/provider/aws/include/feature.go delete mode 100644 x-pack/functionbeat/provider/aws/main.go delete mode 100644 x-pack/functionbeat/provider/aws/main_test.go delete mode 100644 x-pack/functionbeat/provider/local/cmd/root.go delete mode 100644 x-pack/functionbeat/provider/local/include/feature.go delete mode 100644 x-pack/functionbeat/provider/local/local/local.go delete mode 100644 x-pack/functionbeat/provider/local/main.go delete mode 100644 x-pack/functionbeat/provider/local/main_test.go delete mode 100644 x-pack/functionbeat/scripts/mage/config.go delete mode 100644 x-pack/functionbeat/scripts/mage/providers.go delete mode 100644 x-pack/functionbeat/scripts/mage/update.go delete mode 100644 x-pack/functionbeat/tests/system/config/functionbeat.yml.j2 delete mode 100644 x-pack/functionbeat/tests/system/functionbeat.py delete mode 100644 x-pack/functionbeat/tests/system/requirements.txt delete mode 100644 x-pack/functionbeat/tests/system/test_base.py diff --git a/.buildkite/packaging.pipeline.yml b/.buildkite/packaging.pipeline.yml index ecf2dca5cc0f..ec85d9accd45 100644 --- a/.buildkite/packaging.pipeline.yml +++ b/.buildkite/packaging.pipeline.yml @@ -111,7 +111,6 @@ steps: - x-pack/auditbeat - x-pack/dockerlogbeat - x-pack/filebeat - - x-pack/functionbeat - x-pack/heartbeat - x-pack/metricbeat - x-pack/osquerybeat @@ -200,7 +199,6 @@ steps: - x-pack/auditbeat - x-pack/dockerlogbeat - x-pack/filebeat - - x-pack/functionbeat - x-pack/heartbeat - x-pack/metricbeat - x-pack/osquerybeat @@ -269,7 +267,7 @@ steps: - packaging-snapshot - dashboards-snapshot command: | - buildkite-agent artifact download "build/**/*" . + buildkite-agent artifact download "build/**/*" . .buildkite/scripts/packaging/prepare-release-manager.sh snapshot .buildkite/scripts/dra.sh agents: diff --git a/.github/workflows/check-xpack-functionbeat.yml b/.github/workflows/check-xpack-functionbeat.yml deleted file mode 100644 index d51a18ea1a56..000000000000 --- a/.github/workflows/check-xpack-functionbeat.yml +++ /dev/null @@ -1,28 +0,0 @@ -name: check-x-pack-functionbeat - -on: - pull_request: - paths: - - '.github/workflows/check-xpack-functionbeat.yml' - - 'x-pack/functionbeat/**' - - 'functionbeat/**' - -env: - BEAT_MODULE: 'x-pack/functionbeat' - -permissions: - contents: read - -jobs: - check: - runs-on: ubuntu-latest - steps: - - uses: actions/checkout@v4 - - uses: actions/setup-go@v5 - with: - go-version-file: .go-version - - name: Run check/update - run: | - go install github.com/magefile/mage - make -C ${{ env.BEAT_MODULE }} check update - make check-no-changes diff --git a/.github/workflows/updatecli.d/bump-golang-7.17.yml b/.github/workflows/updatecli.d/bump-golang-7.17.yml index 34a60b31c4d4..8c1ba9b42055 100644 --- a/.github/workflows/updatecli.d/bump-golang-7.17.yml +++ b/.github/workflows/updatecli.d/bump-golang-7.17.yml @@ -157,16 +157,6 @@ targets: keyword: "FROM" matcher: "golang" file: ./packetbeat/Dockerfile - update-functionbeat-dockerfile: - name: "Update Functionbeat Dockerfile" - sourceid: latestGoVersion - scmid: githubConfig - kind: dockerfile - spec: - instruction: - keyword: "FROM" - matcher: "golang" - file: ./x-pack/functionbeat/Dockerfile update-nats-module-dockerfile: name: "Update NATS module Dockerfile" sourceid: latestGoVersion diff --git a/.github/workflows/updatecli.d/bump-golang.yml b/.github/workflows/updatecli.d/bump-golang.yml index f03c5471e631..70c831b68baf 100644 --- a/.github/workflows/updatecli.d/bump-golang.yml +++ b/.github/workflows/updatecli.d/bump-golang.yml @@ -166,16 +166,6 @@ targets: keyword: "FROM" matcher: "golang" file: ./packetbeat/Dockerfile - update-functionbeat-dockerfile: - name: "Update Functionbeat Dockerfile" - sourceid: latestGoVersion - scmid: githubConfig - kind: dockerfile - spec: - instruction: - keyword: "FROM" - matcher: "golang" - file: ./x-pack/functionbeat/Dockerfile update-nats-module-dockerfile: name: "Update NATS module Dockerfile" sourceid: latestGoVersion diff --git a/.gitignore b/.gitignore index 70941e281497..b3c2bdc0d986 100644 --- a/.gitignore +++ b/.gitignore @@ -11,7 +11,6 @@ *beat/logs *beat/data **/ironbank/build/ -x-pack/functionbeat/pkg # Files .DS_Store @@ -24,8 +23,6 @@ beat.db *.keystore go_env.properties mage_output_file.go -x-pack/functionbeat/*/fields.yml -x-pack/functionbeat/provider/*/functionbeat-* x-pack/dockerlogbeat/temproot.tar # Editor swap files diff --git a/CHANGELOG.next.asciidoc b/CHANGELOG.next.asciidoc index 9c0fbc06447e..79eb7b66e59d 100644 --- a/CHANGELOG.next.asciidoc +++ b/CHANGELOG.next.asciidoc @@ -440,6 +440,8 @@ https://github.com/elastic/beats/compare/v8.8.1\...main[Check the HEAD diff] *Functionbeat* +- Removal of functionbeat binaries from CI pipelines {issue}40745[40745] {pull}41506[41506] + *Elastic Log Driver* *Elastic Logging Plugin* diff --git a/Makefile b/Makefile index b9be661dc25a..2980974dc047 100644 --- a/Makefile +++ b/Makefile @@ -1,6 +1,6 @@ BUILD_DIR=$(CURDIR)/build COVERAGE_DIR=$(BUILD_DIR)/coverage -BEATS?=auditbeat filebeat heartbeat metricbeat packetbeat winlogbeat x-pack/agentbeat x-pack/auditbeat x-pack/dockerlogbeat x-pack/filebeat x-pack/functionbeat x-pack/heartbeat x-pack/metricbeat x-pack/osquerybeat x-pack/packetbeat x-pack/winlogbeat +BEATS?=auditbeat filebeat heartbeat metricbeat packetbeat winlogbeat x-pack/agentbeat x-pack/auditbeat x-pack/dockerlogbeat x-pack/filebeat x-pack/heartbeat x-pack/metricbeat x-pack/osquerybeat x-pack/packetbeat x-pack/winlogbeat PROJECTS=libbeat x-pack/libbeat $(BEATS) PROJECTS_ENV=libbeat filebeat metricbeat PYTHON_ENV?=$(BUILD_DIR)/python-env diff --git a/NOTICE.txt b/NOTICE.txt index 4f9b5ad5e7fd..dd599cb5cb18 100644 --- a/NOTICE.txt +++ b/NOTICE.txt @@ -1711,11 +1711,11 @@ Contents of probable licence file $GOMODCACHE/github.com/!azure/azure-event-hubs -------------------------------------------------------------------------------- Dependency : github.com/Azure/azure-sdk-for-go -Version: v65.0.0+incompatible +Version: v68.0.0+incompatible Licence type (autodetected): MIT -------------------------------------------------------------------------------- -Contents of probable licence file $GOMODCACHE/github.com/!azure/azure-sdk-for-go@v65.0.0+incompatible/LICENSE.txt: +Contents of probable licence file $GOMODCACHE/github.com/!azure/azure-sdk-for-go@v68.0.0+incompatible/LICENSE.txt: The MIT License (MIT) @@ -4819,12 +4819,12 @@ CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. -------------------------------------------------------------------------------- -Dependency : github.com/aws/aws-lambda-go -Version: v1.44.0 +Dependency : github.com/aws/aws-sdk-go-v2 +Version: v1.30.5 Licence type (autodetected): Apache-2.0 -------------------------------------------------------------------------------- -Contents of probable licence file $GOMODCACHE/github.com/aws/aws-lambda-go@v1.44.0/LICENSE: +Contents of probable licence file $GOMODCACHE/github.com/aws/aws-sdk-go-v2@v1.30.5/LICENSE.txt: Apache License @@ -5030,14 +5030,13 @@ Contents of probable licence file $GOMODCACHE/github.com/aws/aws-lambda-go@v1.44 limitations under the License. - -------------------------------------------------------------------------------- -Dependency : github.com/aws/aws-sdk-go-v2 -Version: v1.30.5 +Dependency : github.com/aws/aws-sdk-go-v2/config +Version: v1.27.29 Licence type (autodetected): Apache-2.0 -------------------------------------------------------------------------------- -Contents of probable licence file $GOMODCACHE/github.com/aws/aws-sdk-go-v2@v1.30.5/LICENSE.txt: +Contents of probable licence file $GOMODCACHE/github.com/aws/aws-sdk-go-v2/config@v1.27.29/LICENSE.txt: Apache License @@ -5244,12 +5243,12 @@ Contents of probable licence file $GOMODCACHE/github.com/aws/aws-sdk-go-v2@v1.30 -------------------------------------------------------------------------------- -Dependency : github.com/aws/aws-sdk-go-v2/config -Version: v1.27.29 +Dependency : github.com/aws/aws-sdk-go-v2/credentials +Version: v1.17.29 Licence type (autodetected): Apache-2.0 -------------------------------------------------------------------------------- -Contents of probable licence file $GOMODCACHE/github.com/aws/aws-sdk-go-v2/config@v1.27.29/LICENSE.txt: +Contents of probable licence file $GOMODCACHE/github.com/aws/aws-sdk-go-v2/credentials@v1.17.29/LICENSE.txt: Apache License @@ -5456,12 +5455,12 @@ Contents of probable licence file $GOMODCACHE/github.com/aws/aws-sdk-go-v2/confi -------------------------------------------------------------------------------- -Dependency : github.com/aws/aws-sdk-go-v2/credentials -Version: v1.17.29 +Dependency : github.com/aws/aws-sdk-go-v2/feature/ec2/imds +Version: v1.16.12 Licence type (autodetected): Apache-2.0 -------------------------------------------------------------------------------- -Contents of probable licence file $GOMODCACHE/github.com/aws/aws-sdk-go-v2/credentials@v1.17.29/LICENSE.txt: +Contents of probable licence file $GOMODCACHE/github.com/aws/aws-sdk-go-v2/feature/ec2/imds@v1.16.12/LICENSE.txt: Apache License @@ -5668,12 +5667,12 @@ Contents of probable licence file $GOMODCACHE/github.com/aws/aws-sdk-go-v2/crede -------------------------------------------------------------------------------- -Dependency : github.com/aws/aws-sdk-go-v2/feature/ec2/imds -Version: v1.16.12 +Dependency : github.com/aws/aws-sdk-go-v2/feature/s3/manager +Version: v1.17.13 Licence type (autodetected): Apache-2.0 -------------------------------------------------------------------------------- -Contents of probable licence file $GOMODCACHE/github.com/aws/aws-sdk-go-v2/feature/ec2/imds@v1.16.12/LICENSE.txt: +Contents of probable licence file $GOMODCACHE/github.com/aws/aws-sdk-go-v2/feature/s3/manager@v1.17.13/LICENSE.txt: Apache License @@ -5880,12 +5879,12 @@ Contents of probable licence file $GOMODCACHE/github.com/aws/aws-sdk-go-v2/featu -------------------------------------------------------------------------------- -Dependency : github.com/aws/aws-sdk-go-v2/feature/s3/manager -Version: v1.17.13 +Dependency : github.com/aws/aws-sdk-go-v2/service/apigateway +Version: v1.25.8 Licence type (autodetected): Apache-2.0 -------------------------------------------------------------------------------- -Contents of probable licence file $GOMODCACHE/github.com/aws/aws-sdk-go-v2/feature/s3/manager@v1.17.13/LICENSE.txt: +Contents of probable licence file $GOMODCACHE/github.com/aws/aws-sdk-go-v2/service/apigateway@v1.25.8/LICENSE.txt: Apache License @@ -6092,12 +6091,12 @@ Contents of probable licence file $GOMODCACHE/github.com/aws/aws-sdk-go-v2/featu -------------------------------------------------------------------------------- -Dependency : github.com/aws/aws-sdk-go-v2/service/apigateway -Version: v1.25.8 +Dependency : github.com/aws/aws-sdk-go-v2/service/apigatewayv2 +Version: v1.22.8 Licence type (autodetected): Apache-2.0 -------------------------------------------------------------------------------- -Contents of probable licence file $GOMODCACHE/github.com/aws/aws-sdk-go-v2/service/apigateway@v1.25.8/LICENSE.txt: +Contents of probable licence file $GOMODCACHE/github.com/aws/aws-sdk-go-v2/service/apigatewayv2@v1.22.8/LICENSE.txt: Apache License @@ -6304,12 +6303,12 @@ Contents of probable licence file $GOMODCACHE/github.com/aws/aws-sdk-go-v2/servi -------------------------------------------------------------------------------- -Dependency : github.com/aws/aws-sdk-go-v2/service/apigatewayv2 -Version: v1.22.8 +Dependency : github.com/aws/aws-sdk-go-v2/service/cloudwatch +Version: v1.40.5 Licence type (autodetected): Apache-2.0 -------------------------------------------------------------------------------- -Contents of probable licence file $GOMODCACHE/github.com/aws/aws-sdk-go-v2/service/apigatewayv2@v1.22.8/LICENSE.txt: +Contents of probable licence file $GOMODCACHE/github.com/aws/aws-sdk-go-v2/service/cloudwatch@v1.40.5/LICENSE.txt: Apache License @@ -6516,12 +6515,12 @@ Contents of probable licence file $GOMODCACHE/github.com/aws/aws-sdk-go-v2/servi -------------------------------------------------------------------------------- -Dependency : github.com/aws/aws-sdk-go-v2/service/cloudformation -Version: v1.53.5 +Dependency : github.com/aws/aws-sdk-go-v2/service/cloudwatchlogs +Version: v1.37.5 Licence type (autodetected): Apache-2.0 -------------------------------------------------------------------------------- -Contents of probable licence file $GOMODCACHE/github.com/aws/aws-sdk-go-v2/service/cloudformation@v1.53.5/LICENSE.txt: +Contents of probable licence file $GOMODCACHE/github.com/aws/aws-sdk-go-v2/service/cloudwatchlogs@v1.37.5/LICENSE.txt: Apache License @@ -6728,12 +6727,12 @@ Contents of probable licence file $GOMODCACHE/github.com/aws/aws-sdk-go-v2/servi -------------------------------------------------------------------------------- -Dependency : github.com/aws/aws-sdk-go-v2/service/cloudwatch -Version: v1.40.5 +Dependency : github.com/aws/aws-sdk-go-v2/service/costexplorer +Version: v1.40.4 Licence type (autodetected): Apache-2.0 -------------------------------------------------------------------------------- -Contents of probable licence file $GOMODCACHE/github.com/aws/aws-sdk-go-v2/service/cloudwatch@v1.40.5/LICENSE.txt: +Contents of probable licence file $GOMODCACHE/github.com/aws/aws-sdk-go-v2/service/costexplorer@v1.40.4/LICENSE.txt: Apache License @@ -6940,12 +6939,12 @@ Contents of probable licence file $GOMODCACHE/github.com/aws/aws-sdk-go-v2/servi -------------------------------------------------------------------------------- -Dependency : github.com/aws/aws-sdk-go-v2/service/cloudwatchlogs -Version: v1.37.5 +Dependency : github.com/aws/aws-sdk-go-v2/service/ec2 +Version: v1.176.0 Licence type (autodetected): Apache-2.0 -------------------------------------------------------------------------------- -Contents of probable licence file $GOMODCACHE/github.com/aws/aws-sdk-go-v2/service/cloudwatchlogs@v1.37.5/LICENSE.txt: +Contents of probable licence file $GOMODCACHE/github.com/aws/aws-sdk-go-v2/service/ec2@v1.176.0/LICENSE.txt: Apache License @@ -7152,12 +7151,12 @@ Contents of probable licence file $GOMODCACHE/github.com/aws/aws-sdk-go-v2/servi -------------------------------------------------------------------------------- -Dependency : github.com/aws/aws-sdk-go-v2/service/costexplorer -Version: v1.40.4 +Dependency : github.com/aws/aws-sdk-go-v2/service/elasticloadbalancingv2 +Version: v1.34.2 Licence type (autodetected): Apache-2.0 -------------------------------------------------------------------------------- -Contents of probable licence file $GOMODCACHE/github.com/aws/aws-sdk-go-v2/service/costexplorer@v1.40.4/LICENSE.txt: +Contents of probable licence file $GOMODCACHE/github.com/aws/aws-sdk-go-v2/service/elasticloadbalancingv2@v1.34.2/LICENSE.txt: Apache License @@ -7364,12 +7363,12 @@ Contents of probable licence file $GOMODCACHE/github.com/aws/aws-sdk-go-v2/servi -------------------------------------------------------------------------------- -Dependency : github.com/aws/aws-sdk-go-v2/service/ec2 -Version: v1.176.0 +Dependency : github.com/aws/aws-sdk-go-v2/service/health +Version: v1.26.4 Licence type (autodetected): Apache-2.0 -------------------------------------------------------------------------------- -Contents of probable licence file $GOMODCACHE/github.com/aws/aws-sdk-go-v2/service/ec2@v1.176.0/LICENSE.txt: +Contents of probable licence file $GOMODCACHE/github.com/aws/aws-sdk-go-v2/service/health@v1.26.4/LICENSE.txt: Apache License @@ -7576,12 +7575,12 @@ Contents of probable licence file $GOMODCACHE/github.com/aws/aws-sdk-go-v2/servi -------------------------------------------------------------------------------- -Dependency : github.com/aws/aws-sdk-go-v2/service/elasticloadbalancingv2 -Version: v1.34.2 +Dependency : github.com/aws/aws-sdk-go-v2/service/iam +Version: v1.35.0 Licence type (autodetected): Apache-2.0 -------------------------------------------------------------------------------- -Contents of probable licence file $GOMODCACHE/github.com/aws/aws-sdk-go-v2/service/elasticloadbalancingv2@v1.34.2/LICENSE.txt: +Contents of probable licence file $GOMODCACHE/github.com/aws/aws-sdk-go-v2/service/iam@v1.35.0/LICENSE.txt: Apache License @@ -7788,12 +7787,12 @@ Contents of probable licence file $GOMODCACHE/github.com/aws/aws-sdk-go-v2/servi -------------------------------------------------------------------------------- -Dependency : github.com/aws/aws-sdk-go-v2/service/health -Version: v1.26.4 +Dependency : github.com/aws/aws-sdk-go-v2/service/organizations +Version: v1.30.3 Licence type (autodetected): Apache-2.0 -------------------------------------------------------------------------------- -Contents of probable licence file $GOMODCACHE/github.com/aws/aws-sdk-go-v2/service/health@v1.26.4/LICENSE.txt: +Contents of probable licence file $GOMODCACHE/github.com/aws/aws-sdk-go-v2/service/organizations@v1.30.3/LICENSE.txt: Apache License @@ -8000,12 +7999,12 @@ Contents of probable licence file $GOMODCACHE/github.com/aws/aws-sdk-go-v2/servi -------------------------------------------------------------------------------- -Dependency : github.com/aws/aws-sdk-go-v2/service/iam -Version: v1.35.0 +Dependency : github.com/aws/aws-sdk-go-v2/service/rds +Version: v1.82.2 Licence type (autodetected): Apache-2.0 -------------------------------------------------------------------------------- -Contents of probable licence file $GOMODCACHE/github.com/aws/aws-sdk-go-v2/service/iam@v1.35.0/LICENSE.txt: +Contents of probable licence file $GOMODCACHE/github.com/aws/aws-sdk-go-v2/service/rds@v1.82.2/LICENSE.txt: Apache License @@ -8212,12 +8211,12 @@ Contents of probable licence file $GOMODCACHE/github.com/aws/aws-sdk-go-v2/servi -------------------------------------------------------------------------------- -Dependency : github.com/aws/aws-sdk-go-v2/service/kinesis -Version: v1.29.5 +Dependency : github.com/aws/aws-sdk-go-v2/service/resourcegroupstaggingapi +Version: v1.23.5 Licence type (autodetected): Apache-2.0 -------------------------------------------------------------------------------- -Contents of probable licence file $GOMODCACHE/github.com/aws/aws-sdk-go-v2/service/kinesis@v1.29.5/LICENSE.txt: +Contents of probable licence file $GOMODCACHE/github.com/aws/aws-sdk-go-v2/service/resourcegroupstaggingapi@v1.23.5/LICENSE.txt: Apache License @@ -8424,12 +8423,12 @@ Contents of probable licence file $GOMODCACHE/github.com/aws/aws-sdk-go-v2/servi -------------------------------------------------------------------------------- -Dependency : github.com/aws/aws-sdk-go-v2/service/organizations -Version: v1.30.3 +Dependency : github.com/aws/aws-sdk-go-v2/service/s3 +Version: v1.60.1 Licence type (autodetected): Apache-2.0 -------------------------------------------------------------------------------- -Contents of probable licence file $GOMODCACHE/github.com/aws/aws-sdk-go-v2/service/organizations@v1.30.3/LICENSE.txt: +Contents of probable licence file $GOMODCACHE/github.com/aws/aws-sdk-go-v2/service/s3@v1.60.1/LICENSE.txt: Apache License @@ -8636,12 +8635,12 @@ Contents of probable licence file $GOMODCACHE/github.com/aws/aws-sdk-go-v2/servi -------------------------------------------------------------------------------- -Dependency : github.com/aws/aws-sdk-go-v2/service/rds -Version: v1.82.2 +Dependency : github.com/aws/aws-sdk-go-v2/service/sqs +Version: v1.34.5 Licence type (autodetected): Apache-2.0 -------------------------------------------------------------------------------- -Contents of probable licence file $GOMODCACHE/github.com/aws/aws-sdk-go-v2/service/rds@v1.82.2/LICENSE.txt: +Contents of probable licence file $GOMODCACHE/github.com/aws/aws-sdk-go-v2/service/sqs@v1.34.5/LICENSE.txt: Apache License @@ -8848,12 +8847,12 @@ Contents of probable licence file $GOMODCACHE/github.com/aws/aws-sdk-go-v2/servi -------------------------------------------------------------------------------- -Dependency : github.com/aws/aws-sdk-go-v2/service/resourcegroupstaggingapi -Version: v1.23.5 +Dependency : github.com/aws/aws-sdk-go-v2/service/sts +Version: v1.30.5 Licence type (autodetected): Apache-2.0 -------------------------------------------------------------------------------- -Contents of probable licence file $GOMODCACHE/github.com/aws/aws-sdk-go-v2/service/resourcegroupstaggingapi@v1.23.5/LICENSE.txt: +Contents of probable licence file $GOMODCACHE/github.com/aws/aws-sdk-go-v2/service/sts@v1.30.5/LICENSE.txt: Apache License @@ -9060,12 +9059,12 @@ Contents of probable licence file $GOMODCACHE/github.com/aws/aws-sdk-go-v2/servi -------------------------------------------------------------------------------- -Dependency : github.com/aws/aws-sdk-go-v2/service/s3 -Version: v1.60.1 +Dependency : github.com/aws/smithy-go +Version: v1.20.4 Licence type (autodetected): Apache-2.0 -------------------------------------------------------------------------------- -Contents of probable licence file $GOMODCACHE/github.com/aws/aws-sdk-go-v2/service/s3@v1.60.1/LICENSE.txt: +Contents of probable licence file $GOMODCACHE/github.com/aws/smithy-go@v1.20.4/LICENSE: Apache License @@ -9243,861 +9242,6 @@ Contents of probable licence file $GOMODCACHE/github.com/aws/aws-sdk-go-v2/servi incurred by, or claims asserted against, such Contributor by reason of your accepting any such warranty or additional liability. - END OF TERMS AND CONDITIONS - - APPENDIX: How to apply the Apache License to your work. - - To apply the Apache License to your work, attach the following - boilerplate notice, with the fields enclosed by brackets "[]" - replaced with your own identifying information. (Don't include - the brackets!) The text should be enclosed in the appropriate - comment syntax for the file format. We also recommend that a - file or class name and description of purpose be included on the - same "printed page" as the copyright notice for easier - identification within third-party archives. - - Copyright [yyyy] [name of copyright owner] - - Licensed under the Apache License, Version 2.0 (the "License"); - you may not use this file except in compliance with the License. - You may obtain a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, - WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - See the License for the specific language governing permissions and - limitations under the License. - - --------------------------------------------------------------------------------- -Dependency : github.com/aws/aws-sdk-go-v2/service/sqs -Version: v1.34.5 -Licence type (autodetected): Apache-2.0 --------------------------------------------------------------------------------- - -Contents of probable licence file $GOMODCACHE/github.com/aws/aws-sdk-go-v2/service/sqs@v1.34.5/LICENSE.txt: - - - Apache License - Version 2.0, January 2004 - http://www.apache.org/licenses/ - - TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION - - 1. Definitions. - - "License" shall mean the terms and conditions for use, reproduction, - and distribution as defined by Sections 1 through 9 of this document. - - "Licensor" shall mean the copyright owner or entity authorized by - the copyright owner that is granting the License. - - "Legal Entity" shall mean the union of the acting entity and all - other entities that control, are controlled by, or are under common - control with that entity. For the purposes of this definition, - "control" means (i) the power, direct or indirect, to cause the - direction or management of such entity, whether by contract or - otherwise, or (ii) ownership of fifty percent (50%) or more of the - outstanding shares, or (iii) beneficial ownership of such entity. - - "You" (or "Your") shall mean an individual or Legal Entity - exercising permissions granted by this License. - - "Source" form shall mean the preferred form for making modifications, - including but not limited to software source code, documentation - source, and configuration files. - - "Object" form shall mean any form resulting from mechanical - transformation or translation of a Source form, including but - not limited to compiled object code, generated documentation, - and conversions to other media types. - - "Work" shall mean the work of authorship, whether in Source or - Object form, made available under the License, as indicated by a - copyright notice that is included in or attached to the work - (an example is provided in the Appendix below). - - "Derivative Works" shall mean any work, whether in Source or Object - form, that is based on (or derived from) the Work and for which the - editorial revisions, annotations, elaborations, or other modifications - represent, as a whole, an original work of authorship. For the purposes - of this License, Derivative Works shall not include works that remain - separable from, or merely link (or bind by name) to the interfaces of, - the Work and Derivative Works thereof. - - "Contribution" shall mean any work of authorship, including - the original version of the Work and any modifications or additions - to that Work or Derivative Works thereof, that is intentionally - submitted to Licensor for inclusion in the Work by the copyright owner - or by an individual or Legal Entity authorized to submit on behalf of - the copyright owner. For the purposes of this definition, "submitted" - means any form of electronic, verbal, or written communication sent - to the Licensor or its representatives, including but not limited to - communication on electronic mailing lists, source code control systems, - and issue tracking systems that are managed by, or on behalf of, the - Licensor for the purpose of discussing and improving the Work, but - excluding communication that is conspicuously marked or otherwise - designated in writing by the copyright owner as "Not a Contribution." - - "Contributor" shall mean Licensor and any individual or Legal Entity - on behalf of whom a Contribution has been received by Licensor and - subsequently incorporated within the Work. - - 2. Grant of Copyright License. Subject to the terms and conditions of - this License, each Contributor hereby grants to You a perpetual, - worldwide, non-exclusive, no-charge, royalty-free, irrevocable - copyright license to reproduce, prepare Derivative Works of, - publicly display, publicly perform, sublicense, and distribute the - Work and such Derivative Works in Source or Object form. - - 3. Grant of Patent License. Subject to the terms and conditions of - this License, each Contributor hereby grants to You a perpetual, - worldwide, non-exclusive, no-charge, royalty-free, irrevocable - (except as stated in this section) patent license to make, have made, - use, offer to sell, sell, import, and otherwise transfer the Work, - where such license applies only to those patent claims licensable - by such Contributor that are necessarily infringed by their - Contribution(s) alone or by combination of their Contribution(s) - with the Work to which such Contribution(s) was submitted. If You - institute patent litigation against any entity (including a - cross-claim or counterclaim in a lawsuit) alleging that the Work - or a Contribution incorporated within the Work constitutes direct - or contributory patent infringement, then any patent licenses - granted to You under this License for that Work shall terminate - as of the date such litigation is filed. - - 4. Redistribution. You may reproduce and distribute copies of the - Work or Derivative Works thereof in any medium, with or without - modifications, and in Source or Object form, provided that You - meet the following conditions: - - (a) You must give any other recipients of the Work or - Derivative Works a copy of this License; and - - (b) You must cause any modified files to carry prominent notices - stating that You changed the files; and - - (c) You must retain, in the Source form of any Derivative Works - that You distribute, all copyright, patent, trademark, and - attribution notices from the Source form of the Work, - excluding those notices that do not pertain to any part of - the Derivative Works; and - - (d) If the Work includes a "NOTICE" text file as part of its - distribution, then any Derivative Works that You distribute must - include a readable copy of the attribution notices contained - within such NOTICE file, excluding those notices that do not - pertain to any part of the Derivative Works, in at least one - of the following places: within a NOTICE text file distributed - as part of the Derivative Works; within the Source form or - documentation, if provided along with the Derivative Works; or, - within a display generated by the Derivative Works, if and - wherever such third-party notices normally appear. The contents - of the NOTICE file are for informational purposes only and - do not modify the License. You may add Your own attribution - notices within Derivative Works that You distribute, alongside - or as an addendum to the NOTICE text from the Work, provided - that such additional attribution notices cannot be construed - as modifying the License. - - You may add Your own copyright statement to Your modifications and - may provide additional or different license terms and conditions - for use, reproduction, or distribution of Your modifications, or - for any such Derivative Works as a whole, provided Your use, - reproduction, and distribution of the Work otherwise complies with - the conditions stated in this License. - - 5. Submission of Contributions. Unless You explicitly state otherwise, - any Contribution intentionally submitted for inclusion in the Work - by You to the Licensor shall be under the terms and conditions of - this License, without any additional terms or conditions. - Notwithstanding the above, nothing herein shall supersede or modify - the terms of any separate license agreement you may have executed - with Licensor regarding such Contributions. - - 6. Trademarks. This License does not grant permission to use the trade - names, trademarks, service marks, or product names of the Licensor, - except as required for reasonable and customary use in describing the - origin of the Work and reproducing the content of the NOTICE file. - - 7. Disclaimer of Warranty. Unless required by applicable law or - agreed to in writing, Licensor provides the Work (and each - Contributor provides its Contributions) on an "AS IS" BASIS, - WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or - implied, including, without limitation, any warranties or conditions - of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A - PARTICULAR PURPOSE. You are solely responsible for determining the - appropriateness of using or redistributing the Work and assume any - risks associated with Your exercise of permissions under this License. - - 8. Limitation of Liability. In no event and under no legal theory, - whether in tort (including negligence), contract, or otherwise, - unless required by applicable law (such as deliberate and grossly - negligent acts) or agreed to in writing, shall any Contributor be - liable to You for damages, including any direct, indirect, special, - incidental, or consequential damages of any character arising as a - result of this License or out of the use or inability to use the - Work (including but not limited to damages for loss of goodwill, - work stoppage, computer failure or malfunction, or any and all - other commercial damages or losses), even if such Contributor - has been advised of the possibility of such damages. - - 9. Accepting Warranty or Additional Liability. While redistributing - the Work or Derivative Works thereof, You may choose to offer, - and charge a fee for, acceptance of support, warranty, indemnity, - or other liability obligations and/or rights consistent with this - License. However, in accepting such obligations, You may act only - on Your own behalf and on Your sole responsibility, not on behalf - of any other Contributor, and only if You agree to indemnify, - defend, and hold each Contributor harmless for any liability - incurred by, or claims asserted against, such Contributor by reason - of your accepting any such warranty or additional liability. - - END OF TERMS AND CONDITIONS - - APPENDIX: How to apply the Apache License to your work. - - To apply the Apache License to your work, attach the following - boilerplate notice, with the fields enclosed by brackets "[]" - replaced with your own identifying information. (Don't include - the brackets!) The text should be enclosed in the appropriate - comment syntax for the file format. We also recommend that a - file or class name and description of purpose be included on the - same "printed page" as the copyright notice for easier - identification within third-party archives. - - Copyright [yyyy] [name of copyright owner] - - Licensed under the Apache License, Version 2.0 (the "License"); - you may not use this file except in compliance with the License. - You may obtain a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, - WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - See the License for the specific language governing permissions and - limitations under the License. - - --------------------------------------------------------------------------------- -Dependency : github.com/aws/aws-sdk-go-v2/service/sts -Version: v1.30.5 -Licence type (autodetected): Apache-2.0 --------------------------------------------------------------------------------- - -Contents of probable licence file $GOMODCACHE/github.com/aws/aws-sdk-go-v2/service/sts@v1.30.5/LICENSE.txt: - - - Apache License - Version 2.0, January 2004 - http://www.apache.org/licenses/ - - TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION - - 1. Definitions. - - "License" shall mean the terms and conditions for use, reproduction, - and distribution as defined by Sections 1 through 9 of this document. - - "Licensor" shall mean the copyright owner or entity authorized by - the copyright owner that is granting the License. - - "Legal Entity" shall mean the union of the acting entity and all - other entities that control, are controlled by, or are under common - control with that entity. For the purposes of this definition, - "control" means (i) the power, direct or indirect, to cause the - direction or management of such entity, whether by contract or - otherwise, or (ii) ownership of fifty percent (50%) or more of the - outstanding shares, or (iii) beneficial ownership of such entity. - - "You" (or "Your") shall mean an individual or Legal Entity - exercising permissions granted by this License. - - "Source" form shall mean the preferred form for making modifications, - including but not limited to software source code, documentation - source, and configuration files. - - "Object" form shall mean any form resulting from mechanical - transformation or translation of a Source form, including but - not limited to compiled object code, generated documentation, - and conversions to other media types. - - "Work" shall mean the work of authorship, whether in Source or - Object form, made available under the License, as indicated by a - copyright notice that is included in or attached to the work - (an example is provided in the Appendix below). - - "Derivative Works" shall mean any work, whether in Source or Object - form, that is based on (or derived from) the Work and for which the - editorial revisions, annotations, elaborations, or other modifications - represent, as a whole, an original work of authorship. For the purposes - of this License, Derivative Works shall not include works that remain - separable from, or merely link (or bind by name) to the interfaces of, - the Work and Derivative Works thereof. - - "Contribution" shall mean any work of authorship, including - the original version of the Work and any modifications or additions - to that Work or Derivative Works thereof, that is intentionally - submitted to Licensor for inclusion in the Work by the copyright owner - or by an individual or Legal Entity authorized to submit on behalf of - the copyright owner. For the purposes of this definition, "submitted" - means any form of electronic, verbal, or written communication sent - to the Licensor or its representatives, including but not limited to - communication on electronic mailing lists, source code control systems, - and issue tracking systems that are managed by, or on behalf of, the - Licensor for the purpose of discussing and improving the Work, but - excluding communication that is conspicuously marked or otherwise - designated in writing by the copyright owner as "Not a Contribution." - - "Contributor" shall mean Licensor and any individual or Legal Entity - on behalf of whom a Contribution has been received by Licensor and - subsequently incorporated within the Work. - - 2. Grant of Copyright License. Subject to the terms and conditions of - this License, each Contributor hereby grants to You a perpetual, - worldwide, non-exclusive, no-charge, royalty-free, irrevocable - copyright license to reproduce, prepare Derivative Works of, - publicly display, publicly perform, sublicense, and distribute the - Work and such Derivative Works in Source or Object form. - - 3. Grant of Patent License. Subject to the terms and conditions of - this License, each Contributor hereby grants to You a perpetual, - worldwide, non-exclusive, no-charge, royalty-free, irrevocable - (except as stated in this section) patent license to make, have made, - use, offer to sell, sell, import, and otherwise transfer the Work, - where such license applies only to those patent claims licensable - by such Contributor that are necessarily infringed by their - Contribution(s) alone or by combination of their Contribution(s) - with the Work to which such Contribution(s) was submitted. If You - institute patent litigation against any entity (including a - cross-claim or counterclaim in a lawsuit) alleging that the Work - or a Contribution incorporated within the Work constitutes direct - or contributory patent infringement, then any patent licenses - granted to You under this License for that Work shall terminate - as of the date such litigation is filed. - - 4. Redistribution. You may reproduce and distribute copies of the - Work or Derivative Works thereof in any medium, with or without - modifications, and in Source or Object form, provided that You - meet the following conditions: - - (a) You must give any other recipients of the Work or - Derivative Works a copy of this License; and - - (b) You must cause any modified files to carry prominent notices - stating that You changed the files; and - - (c) You must retain, in the Source form of any Derivative Works - that You distribute, all copyright, patent, trademark, and - attribution notices from the Source form of the Work, - excluding those notices that do not pertain to any part of - the Derivative Works; and - - (d) If the Work includes a "NOTICE" text file as part of its - distribution, then any Derivative Works that You distribute must - include a readable copy of the attribution notices contained - within such NOTICE file, excluding those notices that do not - pertain to any part of the Derivative Works, in at least one - of the following places: within a NOTICE text file distributed - as part of the Derivative Works; within the Source form or - documentation, if provided along with the Derivative Works; or, - within a display generated by the Derivative Works, if and - wherever such third-party notices normally appear. The contents - of the NOTICE file are for informational purposes only and - do not modify the License. You may add Your own attribution - notices within Derivative Works that You distribute, alongside - or as an addendum to the NOTICE text from the Work, provided - that such additional attribution notices cannot be construed - as modifying the License. - - You may add Your own copyright statement to Your modifications and - may provide additional or different license terms and conditions - for use, reproduction, or distribution of Your modifications, or - for any such Derivative Works as a whole, provided Your use, - reproduction, and distribution of the Work otherwise complies with - the conditions stated in this License. - - 5. Submission of Contributions. Unless You explicitly state otherwise, - any Contribution intentionally submitted for inclusion in the Work - by You to the Licensor shall be under the terms and conditions of - this License, without any additional terms or conditions. - Notwithstanding the above, nothing herein shall supersede or modify - the terms of any separate license agreement you may have executed - with Licensor regarding such Contributions. - - 6. Trademarks. This License does not grant permission to use the trade - names, trademarks, service marks, or product names of the Licensor, - except as required for reasonable and customary use in describing the - origin of the Work and reproducing the content of the NOTICE file. - - 7. Disclaimer of Warranty. Unless required by applicable law or - agreed to in writing, Licensor provides the Work (and each - Contributor provides its Contributions) on an "AS IS" BASIS, - WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or - implied, including, without limitation, any warranties or conditions - of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A - PARTICULAR PURPOSE. You are solely responsible for determining the - appropriateness of using or redistributing the Work and assume any - risks associated with Your exercise of permissions under this License. - - 8. Limitation of Liability. In no event and under no legal theory, - whether in tort (including negligence), contract, or otherwise, - unless required by applicable law (such as deliberate and grossly - negligent acts) or agreed to in writing, shall any Contributor be - liable to You for damages, including any direct, indirect, special, - incidental, or consequential damages of any character arising as a - result of this License or out of the use or inability to use the - Work (including but not limited to damages for loss of goodwill, - work stoppage, computer failure or malfunction, or any and all - other commercial damages or losses), even if such Contributor - has been advised of the possibility of such damages. - - 9. Accepting Warranty or Additional Liability. While redistributing - the Work or Derivative Works thereof, You may choose to offer, - and charge a fee for, acceptance of support, warranty, indemnity, - or other liability obligations and/or rights consistent with this - License. However, in accepting such obligations, You may act only - on Your own behalf and on Your sole responsibility, not on behalf - of any other Contributor, and only if You agree to indemnify, - defend, and hold each Contributor harmless for any liability - incurred by, or claims asserted against, such Contributor by reason - of your accepting any such warranty or additional liability. - - END OF TERMS AND CONDITIONS - - APPENDIX: How to apply the Apache License to your work. - - To apply the Apache License to your work, attach the following - boilerplate notice, with the fields enclosed by brackets "[]" - replaced with your own identifying information. (Don't include - the brackets!) The text should be enclosed in the appropriate - comment syntax for the file format. We also recommend that a - file or class name and description of purpose be included on the - same "printed page" as the copyright notice for easier - identification within third-party archives. - - Copyright [yyyy] [name of copyright owner] - - Licensed under the Apache License, Version 2.0 (the "License"); - you may not use this file except in compliance with the License. - You may obtain a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, - WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - See the License for the specific language governing permissions and - limitations under the License. - - --------------------------------------------------------------------------------- -Dependency : github.com/aws/smithy-go -Version: v1.20.4 -Licence type (autodetected): Apache-2.0 --------------------------------------------------------------------------------- - -Contents of probable licence file $GOMODCACHE/github.com/aws/smithy-go@v1.20.4/LICENSE: - - - Apache License - Version 2.0, January 2004 - http://www.apache.org/licenses/ - - TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION - - 1. Definitions. - - "License" shall mean the terms and conditions for use, reproduction, - and distribution as defined by Sections 1 through 9 of this document. - - "Licensor" shall mean the copyright owner or entity authorized by - the copyright owner that is granting the License. - - "Legal Entity" shall mean the union of the acting entity and all - other entities that control, are controlled by, or are under common - control with that entity. For the purposes of this definition, - "control" means (i) the power, direct or indirect, to cause the - direction or management of such entity, whether by contract or - otherwise, or (ii) ownership of fifty percent (50%) or more of the - outstanding shares, or (iii) beneficial ownership of such entity. - - "You" (or "Your") shall mean an individual or Legal Entity - exercising permissions granted by this License. - - "Source" form shall mean the preferred form for making modifications, - including but not limited to software source code, documentation - source, and configuration files. - - "Object" form shall mean any form resulting from mechanical - transformation or translation of a Source form, including but - not limited to compiled object code, generated documentation, - and conversions to other media types. - - "Work" shall mean the work of authorship, whether in Source or - Object form, made available under the License, as indicated by a - copyright notice that is included in or attached to the work - (an example is provided in the Appendix below). - - "Derivative Works" shall mean any work, whether in Source or Object - form, that is based on (or derived from) the Work and for which the - editorial revisions, annotations, elaborations, or other modifications - represent, as a whole, an original work of authorship. For the purposes - of this License, Derivative Works shall not include works that remain - separable from, or merely link (or bind by name) to the interfaces of, - the Work and Derivative Works thereof. - - "Contribution" shall mean any work of authorship, including - the original version of the Work and any modifications or additions - to that Work or Derivative Works thereof, that is intentionally - submitted to Licensor for inclusion in the Work by the copyright owner - or by an individual or Legal Entity authorized to submit on behalf of - the copyright owner. For the purposes of this definition, "submitted" - means any form of electronic, verbal, or written communication sent - to the Licensor or its representatives, including but not limited to - communication on electronic mailing lists, source code control systems, - and issue tracking systems that are managed by, or on behalf of, the - Licensor for the purpose of discussing and improving the Work, but - excluding communication that is conspicuously marked or otherwise - designated in writing by the copyright owner as "Not a Contribution." - - "Contributor" shall mean Licensor and any individual or Legal Entity - on behalf of whom a Contribution has been received by Licensor and - subsequently incorporated within the Work. - - 2. Grant of Copyright License. Subject to the terms and conditions of - this License, each Contributor hereby grants to You a perpetual, - worldwide, non-exclusive, no-charge, royalty-free, irrevocable - copyright license to reproduce, prepare Derivative Works of, - publicly display, publicly perform, sublicense, and distribute the - Work and such Derivative Works in Source or Object form. - - 3. Grant of Patent License. Subject to the terms and conditions of - this License, each Contributor hereby grants to You a perpetual, - worldwide, non-exclusive, no-charge, royalty-free, irrevocable - (except as stated in this section) patent license to make, have made, - use, offer to sell, sell, import, and otherwise transfer the Work, - where such license applies only to those patent claims licensable - by such Contributor that are necessarily infringed by their - Contribution(s) alone or by combination of their Contribution(s) - with the Work to which such Contribution(s) was submitted. If You - institute patent litigation against any entity (including a - cross-claim or counterclaim in a lawsuit) alleging that the Work - or a Contribution incorporated within the Work constitutes direct - or contributory patent infringement, then any patent licenses - granted to You under this License for that Work shall terminate - as of the date such litigation is filed. - - 4. Redistribution. You may reproduce and distribute copies of the - Work or Derivative Works thereof in any medium, with or without - modifications, and in Source or Object form, provided that You - meet the following conditions: - - (a) You must give any other recipients of the Work or - Derivative Works a copy of this License; and - - (b) You must cause any modified files to carry prominent notices - stating that You changed the files; and - - (c) You must retain, in the Source form of any Derivative Works - that You distribute, all copyright, patent, trademark, and - attribution notices from the Source form of the Work, - excluding those notices that do not pertain to any part of - the Derivative Works; and - - (d) If the Work includes a "NOTICE" text file as part of its - distribution, then any Derivative Works that You distribute must - include a readable copy of the attribution notices contained - within such NOTICE file, excluding those notices that do not - pertain to any part of the Derivative Works, in at least one - of the following places: within a NOTICE text file distributed - as part of the Derivative Works; within the Source form or - documentation, if provided along with the Derivative Works; or, - within a display generated by the Derivative Works, if and - wherever such third-party notices normally appear. The contents - of the NOTICE file are for informational purposes only and - do not modify the License. You may add Your own attribution - notices within Derivative Works that You distribute, alongside - or as an addendum to the NOTICE text from the Work, provided - that such additional attribution notices cannot be construed - as modifying the License. - - You may add Your own copyright statement to Your modifications and - may provide additional or different license terms and conditions - for use, reproduction, or distribution of Your modifications, or - for any such Derivative Works as a whole, provided Your use, - reproduction, and distribution of the Work otherwise complies with - the conditions stated in this License. - - 5. Submission of Contributions. Unless You explicitly state otherwise, - any Contribution intentionally submitted for inclusion in the Work - by You to the Licensor shall be under the terms and conditions of - this License, without any additional terms or conditions. - Notwithstanding the above, nothing herein shall supersede or modify - the terms of any separate license agreement you may have executed - with Licensor regarding such Contributions. - - 6. Trademarks. This License does not grant permission to use the trade - names, trademarks, service marks, or product names of the Licensor, - except as required for reasonable and customary use in describing the - origin of the Work and reproducing the content of the NOTICE file. - - 7. Disclaimer of Warranty. Unless required by applicable law or - agreed to in writing, Licensor provides the Work (and each - Contributor provides its Contributions) on an "AS IS" BASIS, - WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or - implied, including, without limitation, any warranties or conditions - of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A - PARTICULAR PURPOSE. You are solely responsible for determining the - appropriateness of using or redistributing the Work and assume any - risks associated with Your exercise of permissions under this License. - - 8. Limitation of Liability. In no event and under no legal theory, - whether in tort (including negligence), contract, or otherwise, - unless required by applicable law (such as deliberate and grossly - negligent acts) or agreed to in writing, shall any Contributor be - liable to You for damages, including any direct, indirect, special, - incidental, or consequential damages of any character arising as a - result of this License or out of the use or inability to use the - Work (including but not limited to damages for loss of goodwill, - work stoppage, computer failure or malfunction, or any and all - other commercial damages or losses), even if such Contributor - has been advised of the possibility of such damages. - - 9. Accepting Warranty or Additional Liability. While redistributing - the Work or Derivative Works thereof, You may choose to offer, - and charge a fee for, acceptance of support, warranty, indemnity, - or other liability obligations and/or rights consistent with this - License. However, in accepting such obligations, You may act only - on Your own behalf and on Your sole responsibility, not on behalf - of any other Contributor, and only if You agree to indemnify, - defend, and hold each Contributor harmless for any liability - incurred by, or claims asserted against, such Contributor by reason - of your accepting any such warranty or additional liability. - - --------------------------------------------------------------------------------- -Dependency : github.com/awslabs/goformation/v7 -Version: v7.14.9 -Licence type (autodetected): Apache-2.0 --------------------------------------------------------------------------------- - -Contents of probable licence file $GOMODCACHE/github.com/awslabs/goformation/v7@v7.14.9/LICENSE: - - Apache License - Version 2.0, January 2004 - http://www.apache.org/licenses/ - - TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION - - 1. Definitions. - - "License" shall mean the terms and conditions for use, reproduction, - and distribution as defined by Sections 1 through 9 of this document. - - "Licensor" shall mean the copyright owner or entity authorized by - the copyright owner that is granting the License. - - "Legal Entity" shall mean the union of the acting entity and all - other entities that control, are controlled by, or are under common - control with that entity. For the purposes of this definition, - "control" means (i) the power, direct or indirect, to cause the - direction or management of such entity, whether by contract or - otherwise, or (ii) ownership of fifty percent (50%) or more of the - outstanding shares, or (iii) beneficial ownership of such entity. - - "You" (or "Your") shall mean an individual or Legal Entity - exercising permissions granted by this License. - - "Source" form shall mean the preferred form for making modifications, - including but not limited to software source code, documentation - source, and configuration files. - - "Object" form shall mean any form resulting from mechanical - transformation or translation of a Source form, including but - not limited to compiled object code, generated documentation, - and conversions to other media types. - - "Work" shall mean the work of authorship, whether in Source or - Object form, made available under the License, as indicated by a - copyright notice that is included in or attached to the work - (an example is provided in the Appendix below). - - "Derivative Works" shall mean any work, whether in Source or Object - form, that is based on (or derived from) the Work and for which the - editorial revisions, annotations, elaborations, or other modifications - represent, as a whole, an original work of authorship. For the purposes - of this License, Derivative Works shall not include works that remain - separable from, or merely link (or bind by name) to the interfaces of, - the Work and Derivative Works thereof. - - "Contribution" shall mean any work of authorship, including - the original version of the Work and any modifications or additions - to that Work or Derivative Works thereof, that is intentionally - submitted to Licensor for inclusion in the Work by the copyright owner - or by an individual or Legal Entity authorized to submit on behalf of - the copyright owner. For the purposes of this definition, "submitted" - means any form of electronic, verbal, or written communication sent - to the Licensor or its representatives, including but not limited to - communication on electronic mailing lists, source code control systems, - and issue tracking systems that are managed by, or on behalf of, the - Licensor for the purpose of discussing and improving the Work, but - excluding communication that is conspicuously marked or otherwise - designated in writing by the copyright owner as "Not a Contribution." - - "Contributor" shall mean Licensor and any individual or Legal Entity - on behalf of whom a Contribution has been received by Licensor and - subsequently incorporated within the Work. - - 2. Grant of Copyright License. Subject to the terms and conditions of - this License, each Contributor hereby grants to You a perpetual, - worldwide, non-exclusive, no-charge, royalty-free, irrevocable - copyright license to reproduce, prepare Derivative Works of, - publicly display, publicly perform, sublicense, and distribute the - Work and such Derivative Works in Source or Object form. - - 3. Grant of Patent License. Subject to the terms and conditions of - this License, each Contributor hereby grants to You a perpetual, - worldwide, non-exclusive, no-charge, royalty-free, irrevocable - (except as stated in this section) patent license to make, have made, - use, offer to sell, sell, import, and otherwise transfer the Work, - where such license applies only to those patent claims licensable - by such Contributor that are necessarily infringed by their - Contribution(s) alone or by combination of their Contribution(s) - with the Work to which such Contribution(s) was submitted. If You - institute patent litigation against any entity (including a - cross-claim or counterclaim in a lawsuit) alleging that the Work - or a Contribution incorporated within the Work constitutes direct - or contributory patent infringement, then any patent licenses - granted to You under this License for that Work shall terminate - as of the date such litigation is filed. - - 4. Redistribution. You may reproduce and distribute copies of the - Work or Derivative Works thereof in any medium, with or without - modifications, and in Source or Object form, provided that You - meet the following conditions: - - (a) You must give any other recipients of the Work or - Derivative Works a copy of this License; and - - (b) You must cause any modified files to carry prominent notices - stating that You changed the files; and - - (c) You must retain, in the Source form of any Derivative Works - that You distribute, all copyright, patent, trademark, and - attribution notices from the Source form of the Work, - excluding those notices that do not pertain to any part of - the Derivative Works; and - - (d) If the Work includes a "NOTICE" text file as part of its - distribution, then any Derivative Works that You distribute must - include a readable copy of the attribution notices contained - within such NOTICE file, excluding those notices that do not - pertain to any part of the Derivative Works, in at least one - of the following places: within a NOTICE text file distributed - as part of the Derivative Works; within the Source form or - documentation, if provided along with the Derivative Works; or, - within a display generated by the Derivative Works, if and - wherever such third-party notices normally appear. The contents - of the NOTICE file are for informational purposes only and - do not modify the License. You may add Your own attribution - notices within Derivative Works that You distribute, alongside - or as an addendum to the NOTICE text from the Work, provided - that such additional attribution notices cannot be construed - as modifying the License. - - You may add Your own copyright statement to Your modifications and - may provide additional or different license terms and conditions - for use, reproduction, or distribution of Your modifications, or - for any such Derivative Works as a whole, provided Your use, - reproduction, and distribution of the Work otherwise complies with - the conditions stated in this License. - - 5. Submission of Contributions. Unless You explicitly state otherwise, - any Contribution intentionally submitted for inclusion in the Work - by You to the Licensor shall be under the terms and conditions of - this License, without any additional terms or conditions. - Notwithstanding the above, nothing herein shall supersede or modify - the terms of any separate license agreement you may have executed - with Licensor regarding such Contributions. - - 6. Trademarks. This License does not grant permission to use the trade - names, trademarks, service marks, or product names of the Licensor, - except as required for reasonable and customary use in describing the - origin of the Work and reproducing the content of the NOTICE file. - - 7. Disclaimer of Warranty. Unless required by applicable law or - agreed to in writing, Licensor provides the Work (and each - Contributor provides its Contributions) on an "AS IS" BASIS, - WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or - implied, including, without limitation, any warranties or conditions - of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A - PARTICULAR PURPOSE. You are solely responsible for determining the - appropriateness of using or redistributing the Work and assume any - risks associated with Your exercise of permissions under this License. - - 8. Limitation of Liability. In no event and under no legal theory, - whether in tort (including negligence), contract, or otherwise, - unless required by applicable law (such as deliberate and grossly - negligent acts) or agreed to in writing, shall any Contributor be - liable to You for damages, including any direct, indirect, special, - incidental, or consequential damages of any character arising as a - result of this License or out of the use or inability to use the - Work (including but not limited to damages for loss of goodwill, - work stoppage, computer failure or malfunction, or any and all - other commercial damages or losses), even if such Contributor - has been advised of the possibility of such damages. - - 9. Accepting Warranty or Additional Liability. While redistributing - the Work or Derivative Works thereof, You may choose to offer, - and charge a fee for, acceptance of support, warranty, indemnity, - or other liability obligations and/or rights consistent with this - License. However, in accepting such obligations, You may act only - on Your own behalf and on Your sole responsibility, not on behalf - of any other Contributor, and only if You agree to indemnify, - defend, and hold each Contributor harmless for any liability - incurred by, or claims asserted against, such Contributor by reason - of your accepting any such warranty or additional liability. - - END OF TERMS AND CONDITIONS - - APPENDIX: How to apply the Apache License to your work. - - To apply the Apache License to your work, attach the following - boilerplate notice, with the fields enclosed by brackets "{}" - replaced with your own identifying information. (Don't include - the brackets!) The text should be enclosed in the appropriate - comment syntax for the file format. We also recommend that a - file or class name and description of purpose be included on the - same "printed page" as the copyright notice for easier - identification within third-party archives. - - Copyright {yyyy} {name of copyright owner} - - Licensed under the Apache License, Version 2.0 (the "License"); - you may not use this file except in compliance with the License. - You may obtain a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, - WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - See the License for the specific language governing permissions and - limitations under the License. - - --------------------------------------------------------------------------------- -Dependency : github.com/awslabs/kinesis-aggregation/go/v2 -Version: v2.0.0-20220623125934-28468a6701b5 -Licence type (autodetected): Apache-2.0 --------------------------------------------------------------------------------- - -No licence file provided. -------------------------------------------------------------------------------- Dependency : github.com/blakesmith/ar diff --git a/README.md b/README.md index 417436490c22..fff2a7527db1 100644 --- a/README.md +++ b/README.md @@ -20,7 +20,6 @@ Beat | Description --- | --- [Auditbeat](https://github.com/elastic/beats/tree/main/auditbeat) | Collect your Linux audit framework data and monitor the integrity of your files. [Filebeat](https://github.com/elastic/beats/tree/main/filebeat) | Tails and ships log files -[Functionbeat](https://github.com/elastic/beats/tree/main/x-pack/functionbeat) | Read and ships events from serverless infrastructure. [Heartbeat](https://github.com/elastic/beats/tree/main/heartbeat) | Ping remote services for availability [Metricbeat](https://github.com/elastic/beats/tree/main/metricbeat) | Fetches sets of metrics from the operating system and services [Packetbeat](https://github.com/elastic/beats/tree/main/packetbeat) | Monitors the network and applications by sniffing packets @@ -41,7 +40,6 @@ on the [elastic.co site](https://www.elastic.co/guide/): * [Beats platform](https://www.elastic.co/guide/en/beats/libbeat/current/index.html) * [Auditbeat](https://www.elastic.co/guide/en/beats/auditbeat/current/index.html) * [Filebeat](https://www.elastic.co/guide/en/beats/filebeat/current/index.html) -* [Functionbeat](https://www.elastic.co/guide/en/beats/functionbeat/current/index.html) * [Heartbeat](https://www.elastic.co/guide/en/beats/heartbeat/current/index.html) * [Metricbeat](https://www.elastic.co/guide/en/beats/metricbeat/current/index.html) * [Packetbeat](https://www.elastic.co/guide/en/beats/packetbeat/current/index.html) diff --git a/dev-tools/cmd/update_go/update_go_version.go b/dev-tools/cmd/update_go/update_go_version.go index f589abc756dd..df7f74747c1e 100644 --- a/dev-tools/cmd/update_go/update_go_version.go +++ b/dev-tools/cmd/update_go/update_go_version.go @@ -34,7 +34,6 @@ var files = []string{ "libbeat/docs/version.asciidoc", "metricbeat/Dockerfile", "metricbeat/module/http/_meta/Dockerfile", - "x-pack/functionbeat/Dockerfile", "x-pack/libbeat/Dockerfile", } diff --git a/docs/devguide/documentation.asciidoc b/docs/devguide/documentation.asciidoc index d81f79ccb40e..82e12a2721bb 100644 --- a/docs/devguide/documentation.asciidoc +++ b/docs/devguide/documentation.asciidoc @@ -69,7 +69,7 @@ doc collector scripts to regenerate the docs. Make sure you <> and use the correct Go version. The Go version is listed in the `version.asciidoc` file -for the branch you want to update. +for the branch you want to update. To run the docs collector scripts, change to the beats directory and run: @@ -108,7 +108,6 @@ generates * `auditbeat/docs/fields.asciidoc` * `filebeat/docs/fields.asciidoc` -* `functionbeat/docs/fields.asciidoc` * `heartbeat/docs/fields.asciidoc` * `metricbeat/docs/fields.asciidoc` * `packetbeat/docs/fields.asciidoc` diff --git a/go.mod b/go.mod index be5cc26cb320..2e25c7c9de0d 100644 --- a/go.mod +++ b/go.mod @@ -10,7 +10,7 @@ require ( code.cloudfoundry.org/go-loggregator v7.4.0+incompatible code.cloudfoundry.org/rfc5424 v0.0.0-20180905210152-236a6d29298a // indirect github.com/Azure/azure-event-hubs-go/v3 v3.6.1 - github.com/Azure/azure-sdk-for-go v65.0.0+incompatible + github.com/Azure/azure-sdk-for-go v68.0.0+incompatible github.com/Azure/go-ansiterm v0.0.0-20230124172434-306776ec8161 // indirect github.com/Azure/go-autorest/autorest v0.11.29 github.com/Azure/go-autorest/autorest/date v0.3.0 @@ -22,7 +22,6 @@ require ( github.com/akavel/rsrc v0.8.0 // indirect github.com/apoydence/eachers v0.0.0-20181020210610-23942921fe77 // indirect github.com/armon/go-socks5 v0.0.0-20160902184237-e75332964ef5 - github.com/aws/aws-lambda-go v1.44.0 github.com/aws/aws-sdk-go-v2 v1.30.5 github.com/aws/aws-sdk-go-v2/config v1.27.29 github.com/aws/aws-sdk-go-v2/credentials v1.17.29 @@ -172,12 +171,8 @@ require ( github.com/aws/aws-sdk-go-v2/feature/s3/manager v1.17.13 github.com/aws/aws-sdk-go-v2/service/apigateway v1.25.8 github.com/aws/aws-sdk-go-v2/service/apigatewayv2 v1.22.8 - github.com/aws/aws-sdk-go-v2/service/cloudformation v1.53.5 github.com/aws/aws-sdk-go-v2/service/health v1.26.4 - github.com/aws/aws-sdk-go-v2/service/kinesis v1.29.5 github.com/aws/smithy-go v1.20.4 - github.com/awslabs/goformation/v7 v7.14.9 - github.com/awslabs/kinesis-aggregation/go/v2 v2.0.0-20220623125934-28468a6701b5 github.com/dgraph-io/badger/v4 v4.4.0 github.com/elastic/bayeux v1.0.5 github.com/elastic/ebpfevents v0.6.0 @@ -353,6 +348,8 @@ require ( github.com/morikuni/aec v1.0.0 // indirect github.com/munnerz/goautoneg v0.0.0-20191010083416-a7dc8b61c822 // indirect github.com/mxk/go-flowrate v0.0.0-20140419014527-cca7078d478f // indirect + github.com/onsi/ginkgo/v2 v2.17.1 // indirect + github.com/onsi/gomega v1.33.0 // indirect github.com/opencontainers/go-digest v1.0.0 // indirect github.com/opencontainers/image-spec v1.1.0 // indirect github.com/pkg/browser v0.0.0-20240102092130-5ac0b6a4141c // indirect diff --git a/go.sum b/go.sum index 6d5130c89518..cbf4b3eab9ea 100644 --- a/go.sum +++ b/go.sum @@ -46,8 +46,8 @@ github.com/Azure/azure-event-hubs-go/v3 v3.6.1 h1:vSiMmn3tOwgiLyfnmhT5K6Of/3QWRL github.com/Azure/azure-event-hubs-go/v3 v3.6.1/go.mod h1:i2NByb9Pr2na7y8wi/XefEVKkuA2CDUjCNoWQJtTsGo= github.com/Azure/azure-pipeline-go v0.2.3 h1:7U9HBg1JFK3jHl5qmo4CTZKFTVgMwdFHMVtCdfBE21U= github.com/Azure/azure-pipeline-go v0.2.3/go.mod h1:x841ezTBIMG6O3lAcl8ATHnsOPVl2bqk7S3ta6S6u4k= -github.com/Azure/azure-sdk-for-go v65.0.0+incompatible h1:HzKLt3kIwMm4KeJYTdx9EbjRYTySD/t8i1Ee/W5EGXw= -github.com/Azure/azure-sdk-for-go v65.0.0+incompatible/go.mod h1:9XXNKU+eRnpl9moKnB4QOLf1HestfXbmab5FXxiDBjc= +github.com/Azure/azure-sdk-for-go v68.0.0+incompatible h1:fcYLmCpyNYRnvJbPerq7U0hS+6+I79yEDJBqVNcqUzU= +github.com/Azure/azure-sdk-for-go v68.0.0+incompatible/go.mod h1:9XXNKU+eRnpl9moKnB4QOLf1HestfXbmab5FXxiDBjc= github.com/Azure/azure-sdk-for-go/sdk/azcore v1.13.0 h1:GJHeeA2N7xrG3q30L2UXDyuWRzDM900/65j70wcM4Ww= github.com/Azure/azure-sdk-for-go/sdk/azcore v1.13.0/go.mod h1:l38EPgmsp71HHLq9j7De57JcKOWPyhrsW1Awm1JS6K0= github.com/Azure/azure-sdk-for-go/sdk/azidentity v1.7.0 h1:tfLQ34V6F7tVSwoTf/4lH5sE0o6eCJuNDTmH09nDpbc= @@ -155,9 +155,6 @@ github.com/armon/go-radix v1.0.0 h1:F4z6KzEeeQIMeLFa97iZU6vupzoecKdU5TX24SNppXI= github.com/armon/go-radix v1.0.0/go.mod h1:ufUuZ+zHj4x4TnLV4JWEpy2hxWSpsRywHrMgIH9cCH8= github.com/armon/go-socks5 v0.0.0-20160902184237-e75332964ef5 h1:0CwZNZbxp69SHPdPJAN/hZIm0C4OItdklCFmMRWYpio= github.com/armon/go-socks5 v0.0.0-20160902184237-e75332964ef5/go.mod h1:wHh0iHkYZB8zMSxRWpUBQtwG5a7fFgvEO+odwuTv2gs= -github.com/aws/aws-lambda-go v1.44.0 h1:Xp9PANXKsSJ23IhE4ths592uWTCEewswPhSH9qpAuQQ= -github.com/aws/aws-lambda-go v1.44.0/go.mod h1:dpMpZgvWx5vuQJfBt0zqBha60q7Dd7RfgJv23DymV8A= -github.com/aws/aws-sdk-go-v2 v1.9.0/go.mod h1:cK/D0BBs0b/oWPIcX/Z/obahJK1TT7IPVjy53i/mX/4= github.com/aws/aws-sdk-go-v2 v1.30.5 h1:mWSRTwQAb0aLE17dSzztCVJWI9+cRMgqebndjwDyK0g= github.com/aws/aws-sdk-go-v2 v1.30.5/go.mod h1:CT+ZPWXbYrci8chcARI3OmI/qgd+f6WtuLOoaIA8PR0= github.com/aws/aws-sdk-go-v2/aws/protocol/eventstream v1.6.4 h1:70PVAiL15/aBMh5LThwgXdSQorVr91L127ttckI9QQU= @@ -182,8 +179,6 @@ github.com/aws/aws-sdk-go-v2/service/apigateway v1.25.8 h1:CgEyY7gfTf7lHYcCi7+w6 github.com/aws/aws-sdk-go-v2/service/apigateway v1.25.8/go.mod h1:z99ur4Ha5540t8hb5XtqV/UMOnEoEZK22lhr5ZBS0zw= github.com/aws/aws-sdk-go-v2/service/apigatewayv2 v1.22.8 h1:SWBNBbVbThg5Hdi3hWbVaDFjV/OyPbuqZLu4N+mj/Es= github.com/aws/aws-sdk-go-v2/service/apigatewayv2 v1.22.8/go.mod h1:lz2IT8gzzSwao0Pa6uMSdCIPsprmgCkW83q6sHGZFDw= -github.com/aws/aws-sdk-go-v2/service/cloudformation v1.53.5 h1:YeTVIy7cJLeahs7K0jQGDGAd1YYND/to/z8N3kqZBhY= -github.com/aws/aws-sdk-go-v2/service/cloudformation v1.53.5/go.mod h1:y45SdA9v+dLlweaqwAQMoFeXqdRvgwevafa2X8iTqZQ= github.com/aws/aws-sdk-go-v2/service/cloudwatch v1.40.5 h1:/YvqO1j75i4leoV+Z3a5s/dAlEszf2wTKBW8jc3Gd4s= github.com/aws/aws-sdk-go-v2/service/cloudwatch v1.40.5/go.mod h1:maEDlnDRdhsc0xrUljh3dUJbej11AHz+VTQJsNw1QmE= github.com/aws/aws-sdk-go-v2/service/cloudwatchlogs v1.37.5 h1:cQpWa19MrnwPcHQfDjLy6GJLo6lpgbMNix4pt5zLuK0= @@ -206,9 +201,6 @@ github.com/aws/aws-sdk-go-v2/service/internal/presigned-url v1.11.18 h1:tJ5RnkHC github.com/aws/aws-sdk-go-v2/service/internal/presigned-url v1.11.18/go.mod h1:++NHzT+nAF7ZPrHPsA+ENvsXkOO8wEu+C6RXltAG4/c= github.com/aws/aws-sdk-go-v2/service/internal/s3shared v1.17.16 h1:jg16PhLPUiHIj8zYIW6bqzeQSuHVEiWnGA0Brz5Xv2I= github.com/aws/aws-sdk-go-v2/service/internal/s3shared v1.17.16/go.mod h1:Uyk1zE1VVdsHSU7096h/rwnXDzOzYQVl+FNPhPw7ShY= -github.com/aws/aws-sdk-go-v2/service/kinesis v1.6.0/go.mod h1:9O7UG2pELnP0hq35+Gd7XDjOLBkg7tmgRQ0y14ZjoJI= -github.com/aws/aws-sdk-go-v2/service/kinesis v1.29.5 h1:iirGMva2IXw4kcqsvuF+uc8ARweuVqoQJjzRZGaiV1E= -github.com/aws/aws-sdk-go-v2/service/kinesis v1.29.5/go.mod h1:pKTvEQz1PcNd+gKArVyeHpVM63AWnFqYyg07WAQQANQ= github.com/aws/aws-sdk-go-v2/service/organizations v1.30.3 h1:gYS53GRIaSesL04BlZA9MEBzDlENidWR/JDBXhZonFs= github.com/aws/aws-sdk-go-v2/service/organizations v1.30.3/go.mod h1:qdJX3WZbuAan5dXCoinnJjuY1QERCpv3glXeI3+wbeA= github.com/aws/aws-sdk-go-v2/service/rds v1.82.2 h1:kO/fQcueYZvuL5kPzTPQ503cKZj8jyBNg1MlnIqpFPg= @@ -225,13 +217,8 @@ github.com/aws/aws-sdk-go-v2/service/ssooidc v1.26.5 h1:SKvPgvdvmiTWoi0GAJ7AsJfO github.com/aws/aws-sdk-go-v2/service/ssooidc v1.26.5/go.mod h1:20sz31hv/WsPa3HhU3hfrIet2kxM4Pe0r20eBZ20Tac= github.com/aws/aws-sdk-go-v2/service/sts v1.30.5 h1:OMsEmCyz2i89XwRwPouAJvhj81wINh+4UK+k/0Yo/q8= github.com/aws/aws-sdk-go-v2/service/sts v1.30.5/go.mod h1:vmSqFK+BVIwVpDAGZB3CoCXHzurt4qBE8lf+I/kRTh0= -github.com/aws/smithy-go v1.8.0/go.mod h1:SObp3lf9smib00L/v3U2eAKG8FyQ7iLrJnQiAmR5n+E= github.com/aws/smithy-go v1.20.4 h1:2HK1zBdPgRbjFOHlfeQZfpC4r72MOb9bZkiFwggKO+4= github.com/aws/smithy-go v1.20.4/go.mod h1:irrKGvNn1InZwb2d7fkIRNucdfwR8R+Ts3wxYa/cJHg= -github.com/awslabs/goformation/v7 v7.14.9 h1:sZjjpTqXrcBDz4Fi07JWTT7zKM68XsQkW/7iLAJbA/M= -github.com/awslabs/goformation/v7 v7.14.9/go.mod h1:7obldQ8NQ/AkMsgL5K3l4lRMDFB6kCGUloz5dURcXIs= -github.com/awslabs/kinesis-aggregation/go/v2 v2.0.0-20220623125934-28468a6701b5 h1:lxW5Q6K2IisyF5tlr6Ts0W4POGWQZco05MJjFmoeIHs= -github.com/awslabs/kinesis-aggregation/go/v2 v2.0.0-20220623125934-28468a6701b5/go.mod h1:0Qr1uMHFmHsIYMcG4T7BJ9yrJtWadhOmpABCX69dwuc= github.com/benbjohnson/clock v1.1.0/go.mod h1:J11/hYXuz8f4ySSvYwY0FKfm+ezbsZBKZxNJlLklBHA= github.com/benbjohnson/clock v1.3.0 h1:ip6w0uFQkncKQ979AypyG0ER7mqUSBdKLOgAle/AT8A= github.com/benbjohnson/clock v1.3.0/go.mod h1:J11/hYXuz8f4ySSvYwY0FKfm+ezbsZBKZxNJlLklBHA= @@ -507,7 +494,6 @@ github.com/golang/protobuf v1.4.0/go.mod h1:jodUvKwWbYaEsadDk5Fwe5c77LiNKVO9IDvq github.com/golang/protobuf v1.4.1/go.mod h1:U8fpvMrcmy5pZrNK1lt4xCsGvpyWQ/VVv6QDs8UjoX8= github.com/golang/protobuf v1.4.3/go.mod h1:oDoupMAO8OvCJWAcko0GGGIgR6R6ocIYbsSw735rRwI= github.com/golang/protobuf v1.5.0/go.mod h1:FsONVRAS9T7sI+LIUmWTfcYkHO4aIWwzhcaSAoJOfIk= -github.com/golang/protobuf v1.5.2/go.mod h1:XVQd3VNwM+JqD3oG2Ue2ip4fOMUkwXdXDdiuN0vRsmY= github.com/golang/protobuf v1.5.4 h1:i7eJL8qZTpSEXOPTxNKhASYpMn+8e5Q6AdndVa1dWek= github.com/golang/protobuf v1.5.4/go.mod h1:lnTiLA8Wa4RWRcIUkrtSVa5nRhsEGBg48fD6rSs7xps= github.com/golang/snappy v0.0.4 h1:yAGX7huGHXlcLOEtBnF4w7FQwA26wojNCwOYAEhLjQM= @@ -527,7 +513,6 @@ github.com/google/go-cmp v0.4.0/go.mod h1:v8dTdLbMG2kIc/vJvl+f65V22dbkXbowE6jgT/ github.com/google/go-cmp v0.5.0/go.mod h1:v8dTdLbMG2kIc/vJvl+f65V22dbkXbowE6jgT/gNBxE= github.com/google/go-cmp v0.5.2/go.mod h1:v8dTdLbMG2kIc/vJvl+f65V22dbkXbowE6jgT/gNBxE= github.com/google/go-cmp v0.5.3/go.mod h1:v8dTdLbMG2kIc/vJvl+f65V22dbkXbowE6jgT/gNBxE= -github.com/google/go-cmp v0.5.4/go.mod h1:v8dTdLbMG2kIc/vJvl+f65V22dbkXbowE6jgT/gNBxE= github.com/google/go-cmp v0.5.5/go.mod h1:v8dTdLbMG2kIc/vJvl+f65V22dbkXbowE6jgT/gNBxE= github.com/google/go-cmp v0.5.6/go.mod h1:v8dTdLbMG2kIc/vJvl+f65V22dbkXbowE6jgT/gNBxE= github.com/google/go-cmp v0.5.8/go.mod h1:17dUlkBOakJ0+DkrSSNjCkIjxS6bF9zb3elmeNGIjoY= @@ -1191,7 +1176,6 @@ google.golang.org/protobuf v1.23.0/go.mod h1:EGpADcykh3NcUnDUJcl1+ZksZNG86OlYog2 google.golang.org/protobuf v1.23.1-0.20200526195155-81db48ad09cc/go.mod h1:EGpADcykh3NcUnDUJcl1+ZksZNG86OlYog2l/sGQquU= google.golang.org/protobuf v1.25.0/go.mod h1:9JNX74DMeImyA3h4bdi1ymwjUzf21/xIlbajtzgsN7c= google.golang.org/protobuf v1.26.0-rc.1/go.mod h1:jlhhOSvTdKEhbULTjvd4ARK9grFBp09yW+WbY/TyQbw= -google.golang.org/protobuf v1.26.0/go.mod h1:9q0QmTI4eRPtz6boOQmLYwt+qCgq0jsYwAQnmE0givc= google.golang.org/protobuf v1.27.1/go.mod h1:9q0QmTI4eRPtz6boOQmLYwt+qCgq0jsYwAQnmE0givc= google.golang.org/protobuf v1.34.2 h1:6xV6lTsCfpGD21XK49h7MhtcApnLqkfYgPcdHftf6hg= google.golang.org/protobuf v1.34.2/go.mod h1:qYOHts0dSfpeUzUFpOMr/WGzszTmLH+DiWniOlNbLDw= diff --git a/libbeat/docs/command-reference.asciidoc b/libbeat/docs/command-reference.asciidoc index 91daaf097be6..4766152f39fd 100644 --- a/libbeat/docs/command-reference.asciidoc +++ b/libbeat/docs/command-reference.asciidoc @@ -103,9 +103,6 @@ more information, see https://www.elastic.co/subscriptions and [options="header"] |======================= |Commands | -ifeval::["{beatname_lc}"=="functionbeat"] -|<> | {deploy-command-short-desc}. -endif::[] ifdef::apm-server[] |<> |{apikey-command-short-desc}. endif::[] @@ -114,10 +111,6 @@ endif::[] ifndef::serverless[] |<> |{keystore-command-short-desc}. endif::[] -ifeval::["{beatname_lc}"=="functionbeat"] -|<> |{package-command-short-desc}. -|<> |{remove-command-short-desc}. -endif::[] ifdef::has_modules_command[] |<> |{modules-command-short-desc}. endif::[] @@ -126,9 +119,6 @@ ifndef::serverless[] endif::[] |<> |{setup-command-short-desc}. |<> |{test-command-short-desc}. -ifeval::["{beatname_lc}"=="functionbeat"] -|<> |{update-command-short-desc}. -endif::[] |<> |{version-command-short-desc}. |======================= @@ -232,39 +222,6 @@ For more information, see <>. endif::[] -ifeval::["{beatname_lc}"=="functionbeat"] -[[deploy-command]] -==== `deploy` command - -{deploy-command-short-desc}. Before deploying functions, make sure the user has -the credentials required by your cloud service provider. - -*SYNOPSIS* - -["source","sh",subs="attributes"] ----- -{beatname_lc} deploy FUNCTION_NAME [FLAGS] ----- - -*`FUNCTION_NAME`*:: -Specifies the name of the function to deploy. - -*FLAGS* - -*`-h, --help`*:: -Shows help for the `deploy` command. - -{global-flags} - -*EXAMPLES* - -["source","sh",subs="attributes"] ------ -{beatname_lc} deploy cloudwatch -{beatname_lc} deploy sqs ------ -endif::[] - [[export-command]] ==== `export` command @@ -521,68 +478,6 @@ See <> for more examples. endif::[] -ifeval::["{beatname_lc}"=="functionbeat"] -[[package-command]] -==== `package` command - -{package-command-short-desc}. - -*SYNOPSIS* - -["source","sh",subs="attributes"] ----- -{beatname_lc} package [FLAGS] ----- - -*FLAGS* - -*`-h, --help`*:: -Shows help for the `package` command. - -*`-o, --output`*:: -Specifies the full path pattern to use when creating the packages. - -{global-flags} - -*EXAMPLES* - -["source","sh",subs="attributes"] ------ -{beatname_lc} package --output /path/to/folder/package-{{.Provider}}.zip ------ - -[[remove-command]] -==== `remove` command - -{remove-command-short-desc}. Before removing functions, make sure the user has -the credentials required by your cloud service provider. - -*SYNOPSIS* - -["source","sh",subs="attributes"] ----- -{beatname_lc} remove FUNCTION_NAME [FLAGS] ----- - -*`FUNCTION_NAME`*:: -Specifies the name of the function to remove. - -*FLAGS* - -*`-h, --help`*:: -Shows help for the `remove` command. - -{global-flags} - -*EXAMPLES* - -["source","sh",subs="attributes"] ------ -{beatname_lc} remove cloudwatch -{beatname_lc} remove sqs ------ -endif::[] - ifdef::has_modules_command[] [[modules-command]] ==== `modules` command @@ -748,7 +643,7 @@ endif::[] *`--system.hostfs MOUNT_POINT`*:: -Specifies the mount point of the host's filesystem for use in monitoring a host. +Specifies the mount point of the host's filesystem for use in monitoring a host. This flag is depricated, and an alternate hostfs should be specified via the `hostfs` module config value. @@ -961,39 +856,6 @@ ifeval::["{beatname_lc}"=="metricbeat"] ----- endif::[] -ifeval::["{beatname_lc}"=="functionbeat"] -[[update-command]] -==== `update` command - -{update-command-short-desc}. Before updating functions, make sure the user has -the credentials required by your cloud service provider. - -*SYNOPSIS* - -["source","sh",subs="attributes"] ----- -{beatname_lc} update FUNCTION_NAME [FLAGS] ----- - -*`FUNCTION_NAME`*:: -Specifies the name of the function to update. - -*FLAGS* - -*`-h, --help`*:: -Shows help for the `update` command. - -{global-flags} - -*EXAMPLES* - -["source","sh",subs="attributes"] ------ -{beatname_lc} update cloudwatch -{beatname_lc} update sqs ------ -endif::[] - [[version-command]] ==== `version` command diff --git a/libbeat/docs/overview.asciidoc b/libbeat/docs/overview.asciidoc index c76aa8558e54..d42f3e904eb3 100644 --- a/libbeat/docs/overview.asciidoc +++ b/libbeat/docs/overview.asciidoc @@ -9,7 +9,6 @@ for capturing: [horizontal] Audit data:: https://www.elastic.co/products/beats/auditbeat[Auditbeat] Log files and journals:: https://www.elastic.co/products/beats/filebeat[Filebeat] -Cloud data:: https://www.elastic.co/products/beats/functionbeat[Functionbeat] Availability:: https://www.elastic.co/products/beats/heartbeat[Heartbeat] Metrics:: https://www.elastic.co/products/beats/metricbeat[Metricbeat] Network traffic:: https://www.elastic.co/products/beats/packetbeat[Packetbeat] diff --git a/libbeat/publisher/pipeline/sync_client.go b/libbeat/publisher/pipeline/sync_client.go deleted file mode 100644 index 9dcf69ff1550..000000000000 --- a/libbeat/publisher/pipeline/sync_client.go +++ /dev/null @@ -1,106 +0,0 @@ -// Licensed to Elasticsearch B.V. under one or more contributor -// license agreements. See the NOTICE file distributed with -// this work for additional information regarding copyright -// ownership. Elasticsearch B.V. licenses this file to you under -// the Apache License, Version 2.0 (the "License"); you may -// not use this file except in compliance with the License. -// You may obtain a copy of the License at -// -// http://www.apache.org/licenses/LICENSE-2.0 -// -// Unless required by applicable law or agreed to in writing, -// software distributed under the License is distributed on an -// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY -// KIND, either express or implied. See the License for the -// specific language governing permissions and limitations -// under the License. - -package pipeline - -import ( - "sync" - - "github.com/elastic/beats/v7/libbeat/beat" - "github.com/elastic/beats/v7/libbeat/common/acker" - "github.com/elastic/beats/v7/libbeat/publisher/pipetool" - "github.com/elastic/elastic-agent-libs/logp" -) - -// Client implements the interface used by all the functionbeat function, we only implement a synchronous -// client. This interface superseed the core beat.Client interface and can return errors on publish. -type ISyncClient interface { - // Publish accepts a unique events and will publish it to the pipeline. - Publish(beat.Event) error - - // PublishAll accepts a list of multiple events and will publish them to the pipeline. - PublishAll([]beat.Event) error - - // Close closes the current client, no events will be accepted, this method can block if we still - // need to ACK on events. - Close() error - - // Wait blocks until the publisher pipeline send the ACKS for all the events. - Wait() -} - -// SyncClient wraps an existing beat.Client and provide a sync interface. -type SyncClient struct { - client beat.Client - wg sync.WaitGroup - log *logp.Logger -} - -// NewSyncClient creates a new sync clients from the provided configuration, existing ACKs handlers -// defined in the configuration will be proxied by this object. -func NewSyncClient(log *logp.Logger, pipeline beat.Pipeline, cfg beat.ClientConfig) (*SyncClient, error) { - if log == nil { - log = logp.NewLogger("") - } - s := &SyncClient{log: log.Named("sync client")} - - pipeline = pipetool.WithACKer(pipeline, acker.TrackingCounter(func(_, total int) { - log.Debugf("ack callback receives with events count of %d", total) - s.onACK(total) - })) - - c, err := pipeline.ConnectWith(cfg) - if err != nil { - return nil, err - } - - s.client = c - - return s, nil -} - -// Publish publishes one event to the pipeline and return. -func (s *SyncClient) Publish(event beat.Event) error { - s.log.Debug("Publish 1 event") - s.wg.Add(1) - s.client.Publish(event) - return nil -} - -// PublishAll publish a slice of events to the pipeline and return. -func (s *SyncClient) PublishAll(events []beat.Event) error { - s.log.Debugf("Publish %d events", len(events)) - s.wg.Add(len(events)) - s.client.PublishAll(events) - return nil -} - -// Close closes the wrapped beat.Client. -func (s *SyncClient) Close() error { - s.wg.Wait() - return s.client.Close() -} - -// Wait waits until we received a ACK for every events that were sent, this is useful in the -// context of serverless, because when the handler return the execution of the process is suspended. -func (s *SyncClient) Wait() { - s.wg.Wait() -} - -func (s *SyncClient) onACK(n int) { - s.wg.Add(-1 * n) -} diff --git a/libbeat/publisher/pipeline/sync_client_test.go b/libbeat/publisher/pipeline/sync_client_test.go deleted file mode 100644 index 09eac919bd52..000000000000 --- a/libbeat/publisher/pipeline/sync_client_test.go +++ /dev/null @@ -1,132 +0,0 @@ -// Licensed to Elasticsearch B.V. under one or more contributor -// license agreements. See the NOTICE file distributed with -// this work for additional information regarding copyright -// ownership. Elasticsearch B.V. licenses this file to you under -// the Apache License, Version 2.0 (the "License"); you may -// not use this file except in compliance with the License. -// You may obtain a copy of the License at -// -// http://www.apache.org/licenses/LICENSE-2.0 -// -// Unless required by applicable law or agreed to in writing, -// software distributed under the License is distributed on an -// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY -// KIND, either express or implied. See the License for the -// specific language governing permissions and limitations -// under the License. - -package pipeline - -import ( - "testing" - - "github.com/stretchr/testify/assert" - - "github.com/elastic/beats/v7/libbeat/beat" -) - -type dummyClient struct { - Received chan int -} - -func newDummyClient() *dummyClient { - return &dummyClient{Received: make(chan int)} -} - -func (c *dummyClient) Publish(event beat.Event) { - c.Received <- 1 -} - -func (c *dummyClient) PublishAll(events []beat.Event) { - c.Received <- len(events) -} - -func (c *dummyClient) Close() error { - close(c.Received) - return nil -} - -type dummyPipeline struct { - client beat.Client -} - -func newDummyPipeline(client beat.Client) *dummyPipeline { - return &dummyPipeline{client: client} -} - -func (d *dummyPipeline) Connect() (beat.Client, error) { - return d.client, nil -} - -func (d *dummyPipeline) ConnectWith(cfg beat.ClientConfig) (beat.Client, error) { - return d.client, nil -} - -func TestSyncClient(t *testing.T) { - receiver := func(c *dummyClient, sc *SyncClient) { - i := <-c.Received - sc.onACK(i) - } - - t.Run("Publish", func(t *testing.T) { - c := newDummyClient() - - pipeline := newDummyPipeline(c) - sc, err := NewSyncClient(nil, pipeline, beat.ClientConfig{}) - if !assert.NoError(t, err) { - return - } - defer sc.Close() - - go receiver(c, sc) - - err = sc.Publish(beat.Event{}) - if !assert.NoError(t, err) { - return - } - sc.Wait() - }) - - t.Run("PublishAll single ACK", func(t *testing.T) { - c := newDummyClient() - - pipeline := newDummyPipeline(c) - sc, err := NewSyncClient(nil, pipeline, beat.ClientConfig{}) - if !assert.NoError(t, err) { - return - } - defer sc.Close() - - go receiver(c, sc) - - err = sc.PublishAll(make([]beat.Event, 10)) - if !assert.NoError(t, err) { - return - } - sc.Wait() - }) - - t.Run("PublishAll multiple independent ACKs", func(t *testing.T) { - c := newDummyClient() - - pipeline := newDummyPipeline(c) - sc, err := NewSyncClient(nil, pipeline, beat.ClientConfig{}) - if !assert.NoError(t, err) { - return - } - defer sc.Close() - - go func(c *dummyClient, sc *SyncClient) { - <-c.Received - // simulate multiple acks - sc.onACK(5) - sc.onACK(5) - }(c, sc) - - err = sc.PublishAll(make([]beat.Event, 10)) - if !assert.NoError(t, err) { - return - } - sc.Wait() - }) -} diff --git a/x-pack/functionbeat/.gitignore b/x-pack/functionbeat/.gitignore deleted file mode 100644 index e89322a26571..000000000000 --- a/x-pack/functionbeat/.gitignore +++ /dev/null @@ -1,10 +0,0 @@ -.idea -.vagrant -.vscode -/*/_meta/kibana.generated -functionbeat -functionbeat.test -build -data -logs -./fields.yml diff --git a/x-pack/functionbeat/Dockerfile b/x-pack/functionbeat/Dockerfile deleted file mode 100644 index f903da58b533..000000000000 --- a/x-pack/functionbeat/Dockerfile +++ /dev/null @@ -1,25 +0,0 @@ -FROM golang:1.22.9 - -RUN \ - apt-get update \ - && DEBIAN_FRONTEND=noninteractive apt-get install -y --no-install-recommends \ - netcat-openbsd \ - rsync \ - python3 \ - python3-pip \ - python3-venv \ - && rm -rf /var/lib/apt/lists/* - -# Use a virtualenv to avoid the PEP668 "externally managed environment" error caused by conflicts -# with the system Python installation. golang:1.20.6 uses Debian 12 which now enforces PEP668. -ENV VIRTUAL_ENV=/opt/venv -RUN python3 -m venv $VIRTUAL_ENV -ENV PATH="$VIRTUAL_ENV/bin:$PATH" - -RUN pip3 install --upgrade pip==20.1.1 - -# Setup work environment -ENV FUNCTIONBEAT_PATH /go/src/github.com/elastic/beats/x-pack/functionbeat - -RUN mkdir -p $FUNCTIONBEAT_PATH/build/coverage -WORKDIR $FUNCTIONBEAT_PATH diff --git a/x-pack/functionbeat/Jenkinsfile.yml b/x-pack/functionbeat/Jenkinsfile.yml deleted file mode 100644 index d67e79288728..000000000000 --- a/x-pack/functionbeat/Jenkinsfile.yml +++ /dev/null @@ -1,100 +0,0 @@ -when: - branches: true ## for all the branches - changeset: ## when PR contains any of those entries in the changeset - - "^x-pack/functionbeat/.*" - - "@ci" ## special token regarding the changeset for the ci - - "@xpack" ## special token regarding the changeset for the xpack - comments: ## when PR comment contains any of those entries - - "/test x-pack/functionbeat" - labels: ## when PR labels matches any of those entries - - "x-pack-functionbeat" - parameters: ## when parameter was selected in the UI. - - "x-pack-functionbeat" - tags: true ## for all the tags -platform: "immutable && ubuntu-22" ## default label for all the stages -stages: - arm: - mage: "mage build unitTest" - platforms: ## override default label in this specific stage. - - "ubuntu-2204-aarch64" - when: ## Override the top-level when. - comments: - - "/test x-pack/functionbeat for arm" - labels: - - "arm" - parameters: - - "armTest" - stage: extended - unitTest: - mage: "mage build unitTest" - stage: mandatory - goIntegTest: - mage: "mage goIntegTest" - stage: mandatory - macos: - mage: "mage build unitTest" - platforms: ## override default label in this specific stage. - - "macos12 && x86_64" - when: ## Override the top-level when. - comments: - - "/test x-pack/functionbeat for macos" - labels: - - "macOS" - parameters: - - "macosTest" - tags: true ## for all the tags - stage: extended - macosM1: - mage: "mage build unitTest" - platforms: ## override default label in this specific stage. - - "orka && darwin && aarch64" - when: ## Override the top-level when. - comments: - - "/test functonbeat for macos-m1" - labels: - - "macos-m1" - parameters: - - "macosM1Test" - tags: false ## for all the tags - stage: extended - windows-2022: - mage: "mage build unitTest" - platforms: ## override default labels in this specific stage. - - "windows-2022" - stage: mandatory - windows-2019: - mage: "mage build unitTest" - platforms: ## override default labels in this specific stage. - - "windows-2019" - stage: extended_win - windows-2016: - mage: "mage build unitTest" - platforms: ## override default labels in this specific stage. - - "windows-2016" - stage: mandatory - windows-2012: - mage: "mage build unitTest" - platforms: ## override default labels in this specific stage. - - "windows-2012-r2" - stage: extended_win - windows-10: - mage: "mage build unitTest" - platforms: ## override default labels in this specific stage. - - "windows-10" - stage: extended_win - windows-8: - mage: "mage build unitTest" - platforms: ## override default labels in this specific stage. - - "windows-8" - stage: extended_win - packaging-linux: - packaging-linux: "mage package" - e2e: - enabled: false - stage: packaging - when: - branches: false ## Only on a PR basis for the time being - tags: false ## packaging on branches/tags is already in place with the downstream build. - changeset: ## when PR contains any of those entries in the changeset - - "^x-pack/functionbeat/.*" - - "@xpack" ## special token regarding the changeset for the xpack diff --git a/x-pack/functionbeat/Makefile b/x-pack/functionbeat/Makefile deleted file mode 100644 index be4e2ceaeb31..000000000000 --- a/x-pack/functionbeat/Makefile +++ /dev/null @@ -1,10 +0,0 @@ -# -# Variables -# -GOX_FLAGS=-arch="amd64 386 arm ppc64 ppc64le" -ES_BEATS?=../../ - -# -# Includes -# -include $(ES_BEATS)/dev-tools/make/mage.mk diff --git a/x-pack/functionbeat/_meta/config/beat.reference.yml.tmpl b/x-pack/functionbeat/_meta/config/beat.reference.yml.tmpl deleted file mode 100644 index 2f280df4c3ac..000000000000 --- a/x-pack/functionbeat/_meta/config/beat.reference.yml.tmpl +++ /dev/null @@ -1,297 +0,0 @@ -########################## Functionbeat Configuration ########################### - -# This file is a full configuration example documenting all non-deprecated -# options in comments. For a shorter configuration example, that contains only -# the most common options, please see functionbeat.yml in the same directory. -# -# You can find the full configuration reference here: -# https://www.elastic.co/guide/en/beats/functionbeat/index.html - -{{header "Provider"}} -# Configure functions to run on AWS Lambda, currently, we assume that the credentials -# are present in the environment to correctly create the function when using the CLI. -# -# Configure which S3 endpoint should we use. -functionbeat.provider.aws.endpoint: "s3.amazonaws.com" -# Configure which S3 bucket we should upload the lambda artifact. -functionbeat.provider.aws.deploy_bucket: "functionbeat-deploy" - -# Configure credentials of Functionbeat while deploying to AWS. -# Available options: -# * access_key_id, secret_access_key and/or session_token -#functionbeat.provider.aws.access_key_id: '${AWS_ACCESS_KEY_ID:""}' -#functionbeat.provider.aws.secret_access_key: '${AWS_SECRET_ACCESS_KEY:""}' -#functionbeat.provider.aws.session_token: '${AWS_SESSION_TOKEN:""}' -# * role_arn -#functionbeat.provider.aws.role_arn: arn:aws:iam::123456789012:role/test-fnb -# * credential_profile_name and/or shared_credential_file -#functionbeat.provider.aws.credential_profile_name: fnb-aws -#functionbeat.provider.aws.shared_credential_file: /etc/functionbeat/aws_credentials - -functionbeat.provider.aws.functions: - # Define the list of functions available, each function is required to have a unique name. - # Create a function that accepts events coming from cloudwatchlogs. - - name: cloudwatch - enabled: false - type: cloudwatch_logs - - # Description of the method to help identify them when you run multiple functions. - description: "lambda function for cloudwatch logs" - - # Concurrency, is the reserved number of instances for that function. - # Default is 5. - # - # Note: There is a hard limit of 1000 functions of any kind per account. - #concurrency: 5 - - # The maximum memory allocated for this function, the configured size must be a factor of 64. - # There is a hard limit of 3008MiB for each function. Default is 128MiB. - #memory_size: 128MiB - - # The amount of time the function is allowed to run. - #timeout: 3s - - # Execution role of the function. - #role: arn:aws:iam::123456789012:role/MyFunction - - # Connect to private resources in an Amazon VPC. - #virtual_private_cloud: - # security_group_ids: [] - # subnet_ids: [] - - # Dead letter queue configuration, this must be set to an ARN pointing to an SQS queue. - #dead_letter_config.target_arn: - - # Tags are key-value pairs attached to the function. - #tags: - # department: ops - - # Optional fields that you can specify to add additional information to the - # output. Fields can be scalar values, arrays, dictionaries, or any nested - # combination of these. - #fields: - # env: staging - - # List of cloudwatch log group registered to that function. - triggers: - - log_group_name: /aws/lambda/functionbeat-cloudwatch - #filter_pattern: mylog_ - - # Define custom processors for this function. - #processors: - # - dissect: - # tokenizer: "%{key1} %{key2}" - - # Set to true to publish fields with null values in events. - #keep_null: false - - # Create a function that accepts events from SQS queues. - - name: sqs - enabled: false - type: sqs - - # Description of the method to help identify them when you run multiple functions. - description: "lambda function for SQS events" - - # Concurrency, is the reserved number of instances for that function. - # Default is 5. - # - # Note: There is a hard limit of 1000 functions of any kind per account. - #concurrency: 5 - - # The maximum memory allocated for this function, the configured size must be a factor of 64. - # There is a hard limit of 3008MiB for each function. Default is 128MiB. - #memory_size: 128MiB - - # The amount of time the function is allowed to run. - #timeout: 3s - - # Execution role of the function. - #role: arn:aws:iam::123456789012:role/MyFunction - - # Connect to private resources in an Amazon VPC. - #virtual_private_cloud: - # security_group_ids: [] - # subnet_ids: [] - - # Dead letter queue configuration, this must be set to an ARN pointing to an SQS queue. - #dead_letter_config.target_arn: - - # Tags are key-value pairs attached to the function. - #tags: - # department: ops - - # Optional fields that you can specify to add additional information to the - # output. Fields can be scalar values, arrays, dictionaries, or any nested - # combination of these. - #fields: - # env: staging - - # List of SQS queues. - triggers: - # Arn for the SQS queue. - - event_source_arn: arn:aws:sqs:us-east-1:xxxxx:myevents - - # Define custom processors for this function. - #processors: - # - decode_json_fields: - # fields: ["message"] - # process_array: false - # max_depth: 1 - # target: "" - # overwrite_keys: false - # - - # Set to true to publish fields with null values in events. - #keep_null: false - - # Create a function that accepts events from Kinesis streams. - - name: kinesis - enabled: false - type: kinesis - - # Description of the method to help identify them when you run multiple functions. - description: "lambda function for Kinesis events" - - # Concurrency, is the reserved number of instances for that function. - # Default is 5. - # - # Note: There is a hard limit of 1000 functions of any kind per account. - #concurrency: 5 - - # The maximum memory allocated for this function, the configured size must be a factor of 64. - # There is a hard limit of 3008MiB for each function. Default is 128MiB. - #memory_size: 128MiB - - # The amount of time the function is allowed to run. - #timeout: 3s - - # Execution role of the function. - #role: arn:aws:iam::123456789012:role/MyFunction - - # Connect to private resources in an Amazon VPC. - #virtual_private_cloud: - # security_group_ids: [] - # subnet_ids: [] - - # Dead letter queue configuration, this must be set to an ARN pointing to an SQS queue. - #dead_letter_config.target_arn: - - # Tags are key-value pairs attached to the function. - #tags: - # department: ops - - # Optional fields that you can specify to add additional information to the - # output. Fields can be scalar values, arrays, dictionaries, or any nested - # combination of these. - #fields: - # env: staging - - # Define custom processors for this function. - #processors: - # This example extracts the raw data from events. - # - decode_base64_field: - # field: - # from: message - # to: message - # - decompress_gzip_field: - # field: - # from: message - # to: message - # - decode_json_fields: - # fields: ["message"] - # process_array: false - # max_depth: 1 - # target: "" - # overwrite_keys: false - - # List of Kinesis streams. - triggers: - # Arn for the Kinesis stream. - - event_source_arn: arn:aws:kinesis:us-east-1:xxxxx:myevents - - # batch_size is the number of events read in a batch. - # Default is 10. - #batch_size: 100 - - # Starting position is where to start reading events from the Kinesis stream. - # Default is trim_horizon. - #starting_position: "trim_horizon" - - # parallelization_factor is the number of batches to process from each shard concurrently. - # Default is 1. - #parallelization_factor: 1 - - # Set to true to publish fields with null values in events. - #keep_null: false - - # Create a function that accepts Cloudwatch logs from Kinesis streams. - - name: cloudwatch-logs-kinesis - enabled: false - type: cloudwatch_logs_kinesis - - # Description of the method to help identify them when you run multiple functions. - description: "lambda function for Cloudwatch logs in Kinesis events" - - # Set base64_encoded if your data is base64 encoded. - #base64_encoded: false - - # Set compressed if your data is compressed with gzip. - #compressed: true - - # Concurrency, is the reserved number of instances for that function. - # Default is 5. - # - # Note: There is a hard limit of 1000 functions of any kind per account. - #concurrency: 5 - - # The maximum memory allocated for this function, the configured size must be a factor of 64. - # There is a hard limit of 3008MiB for each function. Default is 128MiB. - #memory_size: 128MiB - - # Dead letter queue configuration, this must be set to an ARN pointing to an SQS queue. - #dead_letter_config.target_arn: - - # Tags are key-value pairs attached to the function. - #tags: - # department: ops - - # The amount of time the function is allowed to run. - #timeout: 3s - - # Execution role of the function. - #role: arn:aws:iam::123456789012:role/MyFunction - - # Connect to private resources in an Amazon VPC. - #virtual_private_cloud: - # security_group_ids: [] - # subnet_ids: [] - # - # Define custom processors for this function. - #processors: - # - decode_json_fields: - # fields: ["message"] - # process_array: false - # max_depth: 1 - # target: "" - # overwrite_keys: false - - # List of Kinesis streams. - triggers: - # Arn for the Kinesis stream. - - event_source_arn: arn:aws:kinesis:us-east-1:xxxxx:myevents - - # batch_size is the number of events read in a batch. - # Default is 10. - #batch_size: 100 - - # Starting position is where to start reading events from the Kinesis stream. - # Default is trim_horizon. - #starting_position: "trim_horizon" - - # parallelization_factor is the number of batches to process from each shard concurrently. - # Default is 1. - #parallelization_factor: 1 - - # Set to true to publish fields with null values in events. - #keep_null: false diff --git a/x-pack/functionbeat/_meta/config/beat.yml.tmpl b/x-pack/functionbeat/_meta/config/beat.yml.tmpl deleted file mode 100644 index e3872794a27f..000000000000 --- a/x-pack/functionbeat/_meta/config/beat.yml.tmpl +++ /dev/null @@ -1,253 +0,0 @@ -###################### Functionbeat Configuration Example ####################### - -# This file is an example configuration file highlighting only the most common -# options. The functionbeat.reference.yml file from the same directory contains all the -# supported options with more comments. You can use it as a reference. -# -# You can find the full configuration reference here: -# https://www.elastic.co/guide/en/beats/functionbeat/index.html -# - -{{header "Provider"}} -# Configure functions to run on AWS Lambda, currently, we assume that the credentials -# are present in the environment to correctly create the function when using the CLI. -# -# Configure which S3 endpoint should we use. -functionbeat.provider.aws.endpoint: "s3.amazonaws.com" -# Configure which S3 bucket we should upload the lambda artifact. -functionbeat.provider.aws.deploy_bucket: "functionbeat-deploy" - -functionbeat.provider.aws.functions: - # Define the list of functions available, each function is required to have a unique name. - # Create a function that accepts events coming from cloudwatchlogs. - - name: cloudwatch - enabled: false - type: cloudwatch_logs - - # Description of the method to help identify them when you run multiple functions. - description: "lambda function for cloudwatch logs" - - # Concurrency, is the reserved number of instances for that function. - # Default is 5. - # - # Note: There is a hard limit of 1000 functions of any kind per account. - #concurrency: 5 - - # The maximum memory allocated for this function, the configured size must be a factor of 64. - # There is a hard limit of 3008MiB for each function. Default is 128MiB. - #memory_size: 128MiB - - # Dead letter queue configuration, this must be set to an ARN pointing to an SQS queue. - #dead_letter_config.target_arn: - - # Execution role of the function. - #role: arn:aws:iam::123456789012:role/MyFunction - - # Connect to private resources in an Amazon VPC. - #virtual_private_cloud: - # security_group_ids: [] - # subnet_ids: [] - - # Optional fields that you can specify to add additional information to the - # output. Fields can be scalar values, arrays, dictionaries, or any nested - # combination of these. - #fields: - # env: staging - - # List of cloudwatch log groups registered to that function. - triggers: - - log_group_name: /aws/lambda/functionbeat-cloudwatch_logs - filter_pattern: mylog_ - - # Define custom processors for this function. - #processors: - # - dissect: - # tokenizer: "%{key1} %{key2}" - - # Create a function that accepts events from SQS queues. - - name: sqs - enabled: false - type: sqs - - # Description of the method to help identify them when you run multiple functions. - description: "lambda function for SQS events" - - # Concurrency, is the reserved number of instances for that function. - # Default is 5. - # - # Note: There is a hard limit of 1000 functions of any kind per account. - #concurrency: 5 - - # The maximum memory allocated for this function, the configured size must be a factor of 64. - # There is a hard limit of 3008MiB for each function. Default is 128MiB. - #memory_size: 128MiB - - # Dead letter queue configuration, this must be set to an ARN pointing to an SQS queue. - #dead_letter_config.target_arn: - - # Execution role of the function. - #role: arn:aws:iam::123456789012:role/MyFunction - - # Connect to private resources in an Amazon VPC. - #virtual_private_cloud: - # security_group_ids: [] - # subnet_ids: [] - - # Optional fields that you can specify to add additional information to the - # output. Fields can be scalar values, arrays, dictionaries, or any nested - # combination of these. - #fields: - # env: staging - - # List of SQS queues. - triggers: - # Arn for the SQS queue. - - event_source_arn: arn:aws:sqs:us-east-1:xxxxx:myevents - - # Define custom processors for this function. - #processors: - # - decode_json_fields: - # fields: ["message"] - # process_array: false - # max_depth: 1 - # target: "" - # overwrite_keys: false - # - - # Create a function that accepts events from Kinesis streams. - - name: kinesis - enabled: false - type: kinesis - - # Description of the method to help identify them when you run multiple functions. - description: "lambda function for Kinesis events" - - # Concurrency, is the reserved number of instances for that function. - # Default is 5. - # - # Note: There is a hard limit of 1000 functions of any kind per account. - #concurrency: 5 - - # The maximum memory allocated for this function, the configured size must be a factor of 64. - # There is a hard limit of 3008MiB for each function. Default is 128MiB. - #memory_size: 128MiB - - # Dead letter queue configuration, this must be set to an ARN pointing to an SQS queue. - #dead_letter_config.target_arn: - - # Execution role of the function. - #role: arn:aws:iam::123456789012:role/MyFunction - - # Connect to private resources in an Amazon VPC. - #virtual_private_cloud: - # security_group_ids: [] - # subnet_ids: [] - - # Optional fields that you can specify to add additional information to the - # output. Fields can be scalar values, arrays, dictionaries, or any nested - # combination of these. - #fields: - # env: staging - - # Define custom processors for this function. - #processors: - # This example extracts the raw data from events. - # - decode_base64_field: - # field: - # from: message - # to: message - # - decompress_gzip_field: - # field: - # from: message - # to: message - # - decode_json_fields: - # fields: ["message"] - # process_array: false - # max_depth: 1 - # target: "" - # overwrite_keys: false - - # List of Kinesis streams. - triggers: - # Arn for the Kinesis stream. - - event_source_arn: arn:aws:kinesis:us-east-1:xxxxx:myevents - - # batch_size is the number of events read in a batch. - # Default is 10. - #batch_size: 100 - - # Starting position is where to start reading events from the Kinesis stream. - # Default is trim_horizon. - #starting_position: "trim_horizon" - - # parallelization_factor is the number of batches to process from each shard concurrently. - # Default is 1. - #parallelization_factor: 1 - - # Create a function that accepts Cloudwatch logs from Kinesis streams. - - name: cloudwatch-logs-kinesis - enabled: false - type: cloudwatch_logs_kinesis - - # Description of the method to help identify them when you run multiple functions. - description: "lambda function for Cloudwatch logs in Kinesis events" - - # Set base64_encoded if your data is base64 encoded. - #base64_encoded: false - - # Set compressed if your data is compressed with gzip. - #compressed: true - - # Concurrency, is the reserved number of instances for that function. - # Default is 5. - # - # Note: There is a hard limit of 1000 functions of any kind per account. - #concurrency: 5 - - # The maximum memory allocated for this function, the configured size must be a factor of 64. - # There is a hard limit of 3008MiB for each function. Default is 128MiB. - #memory_size: 128MiB - - # Dead letter queue configuration, this must be set to an ARN pointing to an SQS queue. - #dead_letter_config.target_arn: - - # Execution role of the function. - #role: arn:aws:iam::123456789012:role/MyFunction - - # Connect to private resources in an Amazon VPC. - #virtual_private_cloud: - # security_group_ids: [] - # subnet_ids: [] - - # Optional fields that you can specify to add additional information to the - # output. Fields can be scalar values, arrays, dictionaries, or any nested - # combination of these. - #fields: - # env: staging - - # Define custom processors for this function. - #processors: - # - decode_json_fields: - # fields: ["message"] - # process_array: false - # max_depth: 1 - # target: "" - # overwrite_keys: false - - # List of Kinesis streams. - triggers: - # Arn for the Kinesis stream. - - event_source_arn: arn:aws:kinesis:us-east-1:xxxxx:myevents - - # batch_size is the number of events read in a batch. - # Default is 10. - #batch_size: 100 - - # Starting position is where to start reading events from the Kinesis stream. - # Default is trim_horizon. - #starting_position: "trim_horizon" - - # parallelization_factor is the number of batches to process from each shard concurrently. - # Default is 1. - #parallelization_factor: 1 - diff --git a/x-pack/functionbeat/_meta/fields.yml b/x-pack/functionbeat/_meta/fields.yml deleted file mode 100644 index a150a420e350..000000000000 --- a/x-pack/functionbeat/_meta/fields.yml +++ /dev/null @@ -1,4 +0,0 @@ -- key: functionbeat - title: Functionbeat - description: - fields: diff --git a/x-pack/functionbeat/config/config.go b/x-pack/functionbeat/config/config.go deleted file mode 100644 index 5ae52d96fd20..000000000000 --- a/x-pack/functionbeat/config/config.go +++ /dev/null @@ -1,143 +0,0 @@ -// Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one -// or more contributor license agreements. Licensed under the Elastic License; -// you may not use this file except in compliance with the Elastic License. - -// Config is put into a different package to prevent cyclic imports in case -// it is needed in several locations - -package config - -import ( - "fmt" - "regexp" - - "github.com/elastic/beats/v7/libbeat/cfgfile" - conf "github.com/elastic/elastic-agent-libs/config" -) - -var ( - // We're appending the function name to the role name. - // Limiting this to 30 because, we're prefixing the role name - // with "functionbeat-lambda-"(20 chars) and suffixing with - // the region, the max of which is "ap-southeast-2" (14 chars) - // Length constraints for roleName in AWS is 64 characters max per - // https://docs.aws.amazon.com/IAM/latest/APIReference/API_CreateRole.html - - functionPattern = "^[A-Za-z][A-Za-z0-9\\-]{0,30}$" - functionRE = regexp.MustCompile(functionPattern) - configOverrides = conf.MustNewConfigFrom(map[string]interface{}{ - "path.data": "/tmp", - "path.logs": "/tmp/logs", - "keystore.path": "/tmp/functionbeat.keystore", - "setup.template.enabled": true, - "queue.mem": map[string]interface{}{ - "flush.min_events": 10, - "flush.timeout": "0.01s", - }, - }) - functionLoggingOverrides = conf.MustNewConfigFrom(map[string]interface{}{ - "logging.to_stderr": true, - "logging.to_files": false, - }) - logstashOverrides = conf.MustNewConfigFrom(map[string]interface{}{ - "output.logstash.pipelining": 0, - }) - - // Overrides overrides the default configuration provided by libbeat. - Overrides = []cfgfile.ConditionalOverride{ - cfgfile.ConditionalOverride{ - Check: always, - Config: configOverrides, - }, - cfgfile.ConditionalOverride{ - Check: isLogstash, - Config: logstashOverrides, - }, - } - - functionOverride = cfgfile.ConditionalOverride{ - Check: always, - Config: functionLoggingOverrides, - } - - // FunctionOverrides contain logging settings - FunctionOverrides = append(Overrides, functionOverride) -) - -// Config default configuration for Functionbeat. -type Config struct { - Provider *conf.C `config:"provider" validate:"required"` -} - -// ProviderConfig is a generic configured used by providers. -type ProviderConfig struct { - Functions []*conf.C `config:"functions"` -} - -// FunctionConfig minimal configuration from each function. -type FunctionConfig struct { - Type string `config:"type"` - Name functionName `config:"name"` - Enabled bool `config:"enabled"` -} - -// DefaultConfig is the default configuration for Functionbeat. -var DefaultConfig = Config{} - -// DefaultFunctionConfig is the default configuration for new function. -var DefaultFunctionConfig = FunctionConfig{ - Enabled: true, -} - -var always = func(_ *conf.C) bool { - return true -} - -var isLogstash = func(cfg *conf.C) bool { - return isOutput(cfg, "logstash") -} - -func isOutput(cfg *conf.C, name string) bool { - outputCfg, err := cfg.Child("output", -1) - if err != nil { - return false - } - return outputCfg.HasField(name) -} - -type functionName string - -func (f *functionName) Unpack(s string) error { - if !functionRE.MatchString(s) { - return fmt.Errorf( - "invalid name: '%s', name must match [a-zA-Z0-9-] and be at most 30 characters", - s, - ) - } - *f = functionName(s) - return nil -} - -func (f *functionName) String() string { - return string(*f) -} - -// Validate enforces that function names are unique. -func (p *ProviderConfig) Validate() error { - names := make(map[functionName]bool) - for _, rawfn := range p.Functions { - fc := FunctionConfig{} - rawfn.Unpack(&fc) - - if !fc.Enabled { - return nil - } - - if _, found := names[fc.Name]; found { - return fmt.Errorf("function name '%s' already exist, name must be unique", fc.Name) - } - - names[fc.Name] = true - } - return nil -} diff --git a/x-pack/functionbeat/config/config_test.go b/x-pack/functionbeat/config/config_test.go deleted file mode 100644 index acede0920959..000000000000 --- a/x-pack/functionbeat/config/config_test.go +++ /dev/null @@ -1,128 +0,0 @@ -// Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one -// or more contributor license agreements. Licensed under the Elastic License; -// you may not use this file except in compliance with the Elastic License. - -// Config is put into a different package to prevent cyclic imports in case -// it is needed in several locations - -package config - -import ( - "testing" - - "github.com/stretchr/testify/assert" - - conf "github.com/elastic/elastic-agent-libs/config" -) - -func TestNameMustBeUnique(t *testing.T) { - tests := []struct { - name string - v map[string]interface{} - err bool - }{ - { - name: "not unique names", - err: true, - v: map[string]interface{}{ - "functions": []map[string]interface{}{ - map[string]interface{}{ - "enabled": true, - "type": "cloudwatchlogs", - "name": "ok", - }, - map[string]interface{}{ - "enabled": true, - "type": "cloudwatchlogs", - "name": "ok", - }, - }, - }, - }, - { - name: "not unique names but duplicate is disabled", - err: false, - v: map[string]interface{}{ - "functions": []map[string]interface{}{ - map[string]interface{}{ - "enabled": true, - "type": "cloudwatchlogs", - "name": "ok", - }, - map[string]interface{}{ - "enabled": false, - "type": "cloudwatchlogs", - "name": "ok", - }, - }, - }, - }, - { - name: "name are uniques", - err: false, - v: map[string]interface{}{ - "functions": []map[string]interface{}{ - map[string]interface{}{ - "enabled": true, - "type": "cloudwatchlogs", - "name": "ok", - }, - map[string]interface{}{ - "enabled": true, - "type": "cloudwatchlogs", - "name": "another", - }, - }, - }, - }, - } - - for _, test := range tests { - t.Run(test.name, func(t *testing.T) { - cfg, err := conf.NewConfigFrom(test.v) - if !assert.NoError(t, err) { - return - } - provider := ProviderConfig{} - - err = cfg.Unpack(&provider) - if test.err == true { - assert.Error(t, err) - return - } - assert.NoError(t, err) - }) - } -} - -func TestFunctionName(t *testing.T) { - t.Run("valid function name", func(t *testing.T) { - f := functionName("") - err := f.Unpack("hello-world") - if !assert.NoError(t, err) { - return - } - assert.Equal(t, functionName("hello-world"), f) - }) - - t.Run("valid function name: length of 30 chars", func(t *testing.T) { - f := functionName("") - err := f.Unpack("something-which-is--30--chars") - if !assert.NoError(t, err) { - return - } - assert.Equal(t, functionName("something-which-is--30--chars"), f) - }) - - t.Run("invalid function name", func(t *testing.T) { - f := functionName("") - err := f.Unpack("hello world") - assert.Error(t, err) - }) - - t.Run("invalid function name: length", func(t *testing.T) { - f := functionName("") - err := f.Unpack("something-which-is-greater-than-thirty-characters") - assert.Error(t, err) - }) -} diff --git a/x-pack/functionbeat/conftest.py b/x-pack/functionbeat/conftest.py deleted file mode 100644 index 8e1002b41e5d..000000000000 --- a/x-pack/functionbeat/conftest.py +++ /dev/null @@ -1,5 +0,0 @@ -import os -import sys - -sys.path.append(os.path.join(os.path.dirname(__file__), '../../libbeat/tests/system')) -sys.path.append(os.path.join(os.path.dirname(__file__), './tests/system')) diff --git a/x-pack/functionbeat/dev-tools/packaging/packages.yml b/x-pack/functionbeat/dev-tools/packaging/packages.yml deleted file mode 100644 index 480b31820b5f..000000000000 --- a/x-pack/functionbeat/dev-tools/packaging/packages.yml +++ /dev/null @@ -1,100 +0,0 @@ ---- - -# This file contains the package specifications for Functionbeat. - -shared: - - &common - name: '{{.BeatName}}' - service_name: '{{.BeatServiceName}}' - os: '{{.GOOS}}' - arch: '{{.PackageArch}}' - vendor: '{{.BeatVendor}}' - version: '{{ beat_version }}' - license: '{{.BeatLicense}}' - url: '{{.BeatURL}}' - description: '{{.BeatDescription}}' - - - &binary_files - '{{.BeatName}}{{.BinaryExt}}': - source: build/golang-crossbuild/{{.BeatName}}-{{.GOOS}}-{{.Platform.Arch}}{{.BinaryExt}} - mode: 0755 - fields.yml: - source: fields.yml - mode: 0644 - LICENSE.txt: - source: '{{ repo.RootDir }}/LICENSE.txt' - mode: 0644 - NOTICE.txt: - source: '{{ repo.RootDir }}/NOTICE.txt' - mode: 0644 - README.md: - template: '{{ elastic_beats_dir }}/dev-tools/packaging/templates/common/README.md.tmpl' - mode: 0644 - .build_hash.txt: - content: > - {{ commit }} - mode: 0644 - '{{.BeatName}}.reference.yml': - source: '{{.BeatName}}.reference.yml' - mode: 0644 - '{{.BeatName}}.yml': - source: '{{.BeatName}}.yml' - mode: 0600 - config: true - - # Binary package spec (tar.gz for linux/darwin) - - &binary_spec - <<: *common - files: - <<: *binary_files - - # - # License modifiers for the Elastic License - # - - &elastic_license_for_binaries - license: "Elastic License" - files: - LICENSE.txt: - source: '{{ repo.RootDir }}/licenses/ELASTIC-LICENSE.txt' - mode: 0644 - # - # Binaries used to run functions. - # - - &functionbeat_binaries - files: - pkg/functionbeat-aws: - source: 'provider/aws/build/golang-crossbuild/aws-linux-amd64' - mode: 0755 - -# specs is a list of named packaging "flavors". -specs: - functionbeat: - ### - # Elastic Licensed Packages - ### - - os: windows - types: [zip] - spec: - <<: *binary_spec - <<: *functionbeat_binaries - <<: *elastic_license_for_binaries - files: - '{{.BeatName}}{{.BinaryExt}}': - source: build/golang-crossbuild/{{.BeatName}}-{{.GOOS}}-{{.Platform.Arch}}{{.BinaryExt}} - - - os: darwin - types: [tgz] - spec: - <<: *binary_spec - <<: *functionbeat_binaries - <<: *elastic_license_for_binaries - - - os: linux - types: [tgz] - spec: - <<: *binary_spec - <<: *functionbeat_binaries - <<: *elastic_license_for_binaries - files: - '{{.BeatName}}{{.BinaryExt}}': - source: build/golang-crossbuild/{{.BeatName}}-{{.GOOS}}-{{.Platform.Arch}}{{.BinaryExt}} diff --git a/x-pack/functionbeat/docker-compose.yml b/x-pack/functionbeat/docker-compose.yml deleted file mode 100644 index aa6cc364a7e7..000000000000 --- a/x-pack/functionbeat/docker-compose.yml +++ /dev/null @@ -1,28 +0,0 @@ -version: '2.3' -services: - beat: - build: ${PWD}/. - depends_on: - - proxy_dep - working_dir: /go/src/github.com/elastic/beats/x-pack/functionbeat - volumes: - - ${PWD}/../..:/go/src/github.com/elastic/beats/ - # We launch docker containers to test docker autodiscover: - - /var/run/docker.sock:/var/run/docker.sock - command: make - - # This is a proxy used to block beats until all services are healthy. - # See: https://github.com/docker/compose/issues/4369 - proxy_dep: - image: busybox - depends_on: - elasticsearch: { condition: service_healthy } - - elasticsearch: - extends: - file: ${ES_BEATS}/testing/environments/${TESTING_ENVIRONMENT}.yml - service: elasticsearch - healthcheck: - test: ["CMD-SHELL", "curl -u admin:testing -s http://localhost:9200/_cat/health?h=status | grep -q green"] - retries: 300 - interval: 1s diff --git a/x-pack/functionbeat/docs/config-options-aws.asciidoc b/x-pack/functionbeat/docs/config-options-aws.asciidoc deleted file mode 100644 index 7f0328127f02..000000000000 --- a/x-pack/functionbeat/docs/config-options-aws.asciidoc +++ /dev/null @@ -1,219 +0,0 @@ -[id="configuration-{beatname_lc}-options"] -[role="xpack"] - -:libbeat-xpack-dir: ../../../x-pack/libbeat - -== Configure AWS functions - -++++ -AWS functions -++++ - -{beatname_uc} runs as a function in your serverless environment. - -Before deploying {beatname_uc}, you need to configure one or more functions and -specify details about the services that will trigger the functions. - -You configure the functions in the the +{beatname_lc}.yml+ configuration file. -When you're done, you can <> -to your serverless environment. - -The `aws` functions require AWS credentials configuration in order to make AWS API calls. -Users can either use `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY` and/or -`AWS_SESSION_TOKEN`, or use shared AWS credentials file. -Please see <> for more details. - -The following example configures two functions: `cloudwatch` and `sqs`. The -`cloudwatch` function collects events from CloudWatch Logs. The `sqs` function -collects messages from Amazon Simple Queue Service (SQS). Both functions forward -the events to {es}. - -["source","sh",subs="attributes"] ----- -{beatname_lc}.provider.aws.endpoint: "s3.amazonaws.com" -{beatname_lc}.provider.aws.deploy_bucket: "functionbeat-deploy" -{beatname_lc}.provider.aws.functions: - - name: cloudwatch - enabled: true - type: cloudwatch_logs - description: "lambda function for cloudwatch logs" - triggers: - - log_group_name: /aws/lambda/my-lambda-function - #filter_pattern: mylog_ - - name: sqs - enabled: true - type: sqs - description: "lambda function for SQS events" - triggers: - - event_source_arn: arn:aws:sqs:us-east-1:123456789012:myevents - -cloud.id: "MyESDeployment:SomeLongString==" -cloud.auth: "elastic:SomeLongString" - -processors: - - add_host_metadata: ~ - - add_cloud_metadata: ~ ----- - -[id="{beatname_lc}-options"] -[float] -=== Configuration options -You can specify the following options to configure the functions that you want -to deploy. - -TIP: If you change the configuration after deploying the function, use -the <> to update your deployment. - -[float] -[id="{beatname_lc}-deploy-bucket"] -==== `provider.aws.deploy_bucket` - -A unique name for the S3 bucket that the Lambda artifact will be uploaded to. - -[float] -[id="{beatname_lc}-name"] -==== `name` - -A unique name for the Lambda function. This is the name of the function as it -will appear in the Lambda console on AWS. - -[float] -[id="{beatname_lc}-type"] -==== `type` - -The type of service to monitor. For this release, the supported types -are: - -[horizontal] -`cloudwatch_logs`:: Collects events from CloudWatch logs. -`sqs`:: Collects data from Amazon Simple Queue Service (SQS). -`kinesis`:: Collects data from a Kinesis stream. - -[float] -[id="{beatname_lc}-description"] -==== `description` - -A description of the function. This description is useful when you are running -multiple functions and need more context about how each function is used. - -[float] -[id="{beatname_lc}-triggers"] -==== `triggers` - -A list of triggers that will cause the function to execute. The list of valid -triggers depends on the `type`: - -* For `cloudwatch_logs`, specify a list of log groups. Because the AWS limit is -one subscription filter per CloudWatch log group, the log groups specified here -must have no other subscription filters, or deployment will fail. -For more information, see <>. -* For `sqs` or `kinesis`, specify a list of Amazon Resource Names (ARNs). - -[float] -[id="{beatname_lc}-filter_pattern"] -==== `filter_pattern` - -A regular expression that matches the events you want to collect. Setting this -option may reduce execution costs because the function only executes if there is -data that matches the pattern. - -[float] -[id="{beatname_lc}-concurrency"] -==== `concurrency` - -The reserved number of instances for the function. Setting this option may -reduce execution costs by limiting the number of functions that can execute in -your serverless environment. The default is unreserved. - -[float] -[id="{beatname_lc}-memory-size"] -==== `memory_size` - -The maximum amount of memory to allocate for this function. Specify a value that -is a factor of 64. There is a hard limit of 3008 MiB for each function. The -default is 128 MiB. - -[float] -[id="{beatname_lc}-role"] -==== `role` - -The custom execution role to use for the deployed function. For example: - -[source,yaml] ----- - role: arn:aws:iam::123456789012:role/MyFunction ----- - -Make sure the custom role has the permissions required to run the function. For -more information, see <>. - -If `role` is not specified, the function uses the default role and policy -created during deployment. - -[float] -[id="{beatname_lc}-virtual_private_cloud"] -==== `virtual_private_cloud` - -Specifies additional settings required to connect to private resources in an -Amazon Virtual Private Cloud (VPC). For example: - -[source,yaml] ----- - virtual_private_cloud: - security_group_ids: - - mySecurityGroup - - anotherSecurityGroup - subnet_ids: - - myUniqueID ----- - -[float] -[id="{beatname_lc}-dead-letter-config"] -==== `dead_letter_config.target_arn` - -The dead letter queue to use for messages that can't be processed successfully. -Set this option to an ARN that points to an SQS queue. - -[float] -[id="{beatname_lc}-batch-size"] -==== `batch_size` - -The number of events to read from a Kinesis stream, the minimum value is 100 and the maximum is -10000. The default is 100. - -[float] -[id="{beatname_lc}-starting-position"] -==== `starting_position` - -The starting position to read from a Kinesis stream, valids values are `trim_horizon` and `latest`. -The default is trim_horizon. - -[float] -[id="{beatname_lc}-parallelization-factor"] -==== `parallelization_factor` - -The number of batches to process from each shard concurrently, the minimum value is 1 and the maximum is 10 -The default is 1. - -[float] -[id="{beatname_lc}-keep-null"] -==== `keep_null` - -If this option is set to true, fields with `null` values will be published in -the output document. By default, `keep_null` is set to `false`. - -[float] -[id="{beatname_lc}-index"] -==== `index` - -If present, this formatted string overrides the index for events from this function -(for elasticsearch outputs), or sets the `raw_index` field of the event's -metadata (for other outputs). This string can only refer to the agent name and -version and the event timestamp; for access to dynamic fields, use -`output.elasticsearch.index` or a processor. - -Example value: `"%{[agent.name]}-myindex-%{+yyyy.MM.dd}"` might -expand to `"functionbeat-myindex-2019.12.13"`. - -[id="aws-credentials-config"] -include::{libbeat-xpack-dir}/docs/aws-credentials-config.asciidoc[] diff --git a/x-pack/functionbeat/docs/configuring-howto.asciidoc b/x-pack/functionbeat/docs/configuring-howto.asciidoc deleted file mode 100644 index fad0629261be..000000000000 --- a/x-pack/functionbeat/docs/configuring-howto.asciidoc +++ /dev/null @@ -1,66 +0,0 @@ -[id="configuring-howto-{beatname_lc}"] -[role="xpack"] -= Configure {beatname_uc} - -[partintro] --- -++++ -Configure -++++ - -include::{libbeat-dir}/shared/configuring-intro.asciidoc[] - -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <<{beatname_lc}-reference-yml>> - --- - -include::./config-options-aws.asciidoc[] - -include::./general-options.asciidoc[] - -[role="xpack"] -include::{libbeat-dir}/outputconfig.asciidoc[] - -ifndef::no_kerberos[] -include::{libbeat-dir}/shared-kerberos-config.asciidoc[] -endif::[] - -[role="xpack"] -include::{libbeat-dir}/shared-ssl-config.asciidoc[] - -[role="xpack"] -include::{libbeat-dir}/shared-ilm.asciidoc[] - -[role="xpack"] -include::{libbeat-dir}/setup-config.asciidoc[] - -[role="xpack"] -include::./filtering.asciidoc[] - -:allplatforms: -[role="xpack"] -include::{libbeat-dir}/queueconfig.asciidoc[] -:allplatforms!: - -[role="xpack"] -include::{libbeat-dir}/loggingconfig.asciidoc[] - -[role="xpack"] -include::{libbeat-dir}/regexp.asciidoc[] - -[role="xpack"] -include::{libbeat-dir}/shared-instrumentation.asciidoc[] - -[role="xpack"] -include::{libbeat-dir}/reference-yml.asciidoc[] diff --git a/x-pack/functionbeat/docs/deploying.asciidoc b/x-pack/functionbeat/docs/deploying.asciidoc deleted file mode 100644 index 5cfe9d98982d..000000000000 --- a/x-pack/functionbeat/docs/deploying.asciidoc +++ /dev/null @@ -1,113 +0,0 @@ -[id="deploy-to-cloud-provider"] -[role="xpack"] -=== Deploy {beatname_uc} to your cloud provider - -After configuring {beatname_uc} and defining cloud functions for the services -you want to monitor, deploy the functions to your cloud provider. To do this, -you can use the {beatname_uc} manager (good for getting started), or use your -own deployment infrastructure. - -[[manager-deployment]] -==== Use the {beatname_uc} manager - -Use the built-in manager to deploy, update, or delete {beatname_uc} functions -when you don't have your own deployment infrastructure or process in place. - -During deployment, the {beatname_uc} manager: - -* Exports a function template to use for deployment. For AWS, it exports an -{cloudformation-ref} template. To inspect the template, run the -<> command. -* Creates a zip package that includes the function code and +{beatname_lc}.yml+ -config file. -* Uploads the package to the specified cloud provider. - -See <<{beatname_lc}-deploying>> in the getting started to learn how to deploy -functions by using the {beatname_uc} manager. - -[[own-deployment]] -==== Use your own deployment infrastructure - -If you don't want to use the {beatname_uc} manager, use your own deployment -infrastructure. To do this, create a package, then deploy it to your cloud -provider: - -. Set the following environment variables: -+ -`BEAT_STRICT_PERMS=false`:: This setting makes the function skip the ownership -check on the configuration file. -`ENABLED_FUNCTIONS=function-name-1,function-name-2`:: Specifies a -comma-separated list of functions that are enabled in the configuration file. For -example, to package functions called `my-kinesis` and `my-cloudwatch-logs`, run: -+ -*linux and mac*: -+ -[source, shell] ----- -export BEAT_STRICT_PERMS=false -export ENABLED_FUNCTIONS=my-kinesis,my-cloudwatch-logs ----- -+ -*win*: -+ -[source, shell] ----- -set BEAT_STRICT_PERMS=false -set ENABLED_FUNCTIONS=my-kinesis,my-cloudwatch-logs ----- -+ -TIP: For easier management, we recommend having one Lambda per function. - -. Run the `package` command to package the functions and dependencies into an -archive. For example: -+ -*linux and mac:* -+ -["source","sh",subs="attributes"] ----------------------------------------------------------------------- -./{beatname_lc} -v -e -d "*" package --output /path/to/folder/package-{{.Provider}}.zip ----------------------------------------------------------------------- -+ -*win:* -+ -["source","sh",subs="attributes"] ----------------------------------------------------------------------- -.{backslash}{beatname_lc}.exe -v -e -d "*" package --output /path/to/folder/package-{{.Provider}}.zip ----------------------------------------------------------------------- -+ -For `--output` specify a full path pattern. -+ -The `package` command generates deployment packages for each provider specified -in the configuration. Each package contains: -+ -* a binary with the function code -* the `functionbeat.yml` config file - -. If certificates are required, add the cert files to the zip package under the -same path as the configured +{beatname_lc}.yml+ file. - -. Export a function template to use for deployment: -+ -*linux and mac:* -+ -["source","sh",subs="attributes"] ----------------------------------------------------------------------- -./{beatname_lc} export function FUNCTION_NAME ----------------------------------------------------------------------- -+ -*win:* -+ -["source","sh",subs="attributes"] ----------------------------------------------------------------------- -.{backslash}{beatname_lc}.exe export function FUNCTION_NAME ----------------------------------------------------------------------- -+ -{beatname_uc} writes the template to stdout. For AWS functions, it writes an -{cloudformation-ref} template. - -. Modify the template to work with your infrastructure. - -. Deploy the package, using the infrastructure and automation supported by your -cloud provider, for example, {cloudformation-ref}. -+ -For more information about deployment, see your cloud provider's documentation. diff --git a/x-pack/functionbeat/docs/export-cloudformation-template.asciidoc b/x-pack/functionbeat/docs/export-cloudformation-template.asciidoc deleted file mode 100644 index 803ab5a6f8b4..000000000000 --- a/x-pack/functionbeat/docs/export-cloudformation-template.asciidoc +++ /dev/null @@ -1,27 +0,0 @@ -[[export-cloudformation-template]] -[role="xpack"] -=== Export AWS CloudFormation template - -You can use {beatname_uc} to export an {cloudformation-ref} template then use -the template with automation software to deploy {beatname_uc} code to your cloud -environment. - -After configuring {beatname_uc}, use the following command to export the -CloudFormation template: - -*linux and mac:* - -["source","sh",subs="attributes"] ----------------------------------------------------------------------- -./{beatname_lc} export function FUNCTION_NAME ----------------------------------------------------------------------- - -*win:* - -["source","sh",subs="attributes"] ----------------------------------------------------------------------- -.{backslash}{beatname_lc}.exe export function FUNCTION_NAME ----------------------------------------------------------------------- - -{beatname_uc} writes the CloudFormation template to stdout. Modify the template -to work with your infrastructure. diff --git a/x-pack/functionbeat/docs/faq-resource-limit.asciidoc b/x-pack/functionbeat/docs/faq-resource-limit.asciidoc deleted file mode 100644 index c4db5a4c6831..000000000000 --- a/x-pack/functionbeat/docs/faq-resource-limit.asciidoc +++ /dev/null @@ -1,55 +0,0 @@ -[[unable-to-deploy-resource-limit]] -=== Deployment to AWS fails with "resource limit exceeded" - -Deployment fails with the following message if you attempt to deploy a Lambda -function that reads from a CloudWatch log group that already has a subscription -filter defined on it: - -[source,shell] ----- -CREATE_FAILED, ResourceStatusReason: Resource limit exceeded ----- - -The AWS limit on subscription filters is one per log group. If you've already -deployed a Lambda function that monitors the log group, even if you deleted the -function, the filter subscription might still exist. - -To resolve this issue, use the AWS logs -https://docs.aws.amazon.com/cli/latest/reference/logs/describe-subscription-filters.html[`describe-subscription-filters`] -command on the log group. For example, if you're using the AWS CLI, run: - -[source,shell] ----- -aws logs describe-subscription-filters --log-group-name /aws/lambda/hello-world-python ----- - -The output will look something like: - -[source,json] ----- -{ - "subscriptionFilters": [ - { - "filterPattern": "", - "filterName": "fnb-cloudwatch-stack-fnbcloudwatch3SFawslambdahelloworldpython-11WH0BC1BM1NP", - "creationTime": 1565194872642, - "logGroupName": "/aws/lambda/hello-world-python", - "destinationArn": "arn:aws:lambda:us-east-2:551009506772:function:cloudwatch", - "distribution": "ByLogStream" - } - ] -} ----- - -If you're no longer using the subscription filter, you can use the AWS logs -https://docs.aws.amazon.com/cli/latest/reference/logs/delete-subscription-filter.html[`delete-subscription-filter`] -command to delete it. For example: - -[source,shell] ----- -aws logs delete-subscription-filter --log-group-name /aws/lambda/hello-world-python --filter-name fnb-cloudwatch-stack-fnbcloudwatch3SFawslambdahelloworldpython-11WH0BC1BM1NP ----- - -Before attempting to redeploy the function, you might need to go to the -CloudFormation console in AWS and delete the stack that {beatname_uc} -created for the failed deployment. diff --git a/x-pack/functionbeat/docs/faq.asciidoc b/x-pack/functionbeat/docs/faq.asciidoc deleted file mode 100644 index 6e942b9633cd..000000000000 --- a/x-pack/functionbeat/docs/faq.asciidoc +++ /dev/null @@ -1,23 +0,0 @@ -[[faq]] -[role="xpack"] -== Common problems - -This section describes common problems you might encounter with -{beatname_uc}. Also check out the -https://discuss.elastic.co/c/beats/{beatname_lc}[{beatname_uc} discussion forum]. - -[[unable-to-deploy]] -=== Deployment to AWS fails with "failed to create the stack" - -Deployment fails if you attempt to deploy the Lambda function to the wrong -region. - -You must deploy the function to the region where your services are running. For -example, if you want to monitor CloudWatch logs for a service running in the -`us-east-1` region, you must deploy the Lambda function to the same region, or -deployment fails. - -include::faq-resource-limit.asciidoc[] - -include::{libbeat-dir}/shared-faq.asciidoc[] - diff --git a/x-pack/functionbeat/docs/fields.asciidoc b/x-pack/functionbeat/docs/fields.asciidoc deleted file mode 100644 index 08589bd02996..000000000000 --- a/x-pack/functionbeat/docs/fields.asciidoc +++ /dev/null @@ -1,15676 +0,0 @@ - -//// -This file is generated! See _meta/fields.yml and scripts/generate_fields_docs.py -//// - -:edit_url: - -[[exported-fields]] -= Exported fields - -[partintro] - --- -This document describes the fields that are exported by Functionbeat. They are -grouped in the following categories: - -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> - --- -[[exported-fields-beat-common]] -== Beat fields - -Contains common beat fields available in all event types. - - - -*`agent.hostname`*:: -+ --- -Deprecated - use agent.name or agent.id to identify an agent. - - -type: alias - -alias to: agent.name - --- - -*`beat.timezone`*:: -+ --- -type: alias - -alias to: event.timezone - --- - -*`fields`*:: -+ --- -Contains user configurable fields. - - -type: object - --- - -*`beat.name`*:: -+ --- -type: alias - -alias to: host.name - --- - -*`beat.hostname`*:: -+ --- -type: alias - -alias to: agent.name - --- - -*`timeseries.instance`*:: -+ --- -Time series instance id - -type: keyword - --- - -[[exported-fields-cloud]] -== Cloud provider metadata fields - -Metadata from cloud providers added by the add_cloud_metadata processor. - - - -*`cloud.image.id`*:: -+ --- -Image ID for the cloud instance. - - -example: ami-abcd1234 - --- - -*`meta.cloud.provider`*:: -+ --- -type: alias - -alias to: cloud.provider - --- - -*`meta.cloud.instance_id`*:: -+ --- -type: alias - -alias to: cloud.instance.id - --- - -*`meta.cloud.instance_name`*:: -+ --- -type: alias - -alias to: cloud.instance.name - --- - -*`meta.cloud.machine_type`*:: -+ --- -type: alias - -alias to: cloud.machine.type - --- - -*`meta.cloud.availability_zone`*:: -+ --- -type: alias - -alias to: cloud.availability_zone - --- - -*`meta.cloud.project_id`*:: -+ --- -type: alias - -alias to: cloud.project.id - --- - -*`meta.cloud.region`*:: -+ --- -type: alias - -alias to: cloud.region - --- - -[[exported-fields-docker-processor]] -== Docker fields - -Docker stats collected from Docker. - - - - -*`docker.container.id`*:: -+ --- -type: alias - -alias to: container.id - --- - -*`docker.container.image`*:: -+ --- -type: alias - -alias to: container.image.name - --- - -*`docker.container.name`*:: -+ --- -type: alias - -alias to: container.name - --- - -*`docker.container.labels`*:: -+ --- -Image labels. - - -type: object - --- - -[[exported-fields-ecs]] -== ECS fields - - -This section defines Elastic Common Schema (ECS) fields—a common set of fields -to be used when storing event data in {es}. - -This is an exhaustive list, and fields listed here are not necessarily used by {beatname_uc}. -The goal of ECS is to enable and encourage users of {es} to normalize their event data, -so that they can better analyze, visualize, and correlate the data represented in their events. - -See the {ecs-ref}[ECS reference] for more information. - -*`@timestamp`*:: -+ --- -Date/time when the event originated. -This is the date/time extracted from the event, typically representing when the event was generated by the source. -If the event source has no original timestamp, this value is typically populated by the first time the event was received by the pipeline. -Required field for all events. - -type: date - -example: 2016-05-23T08:05:34.853Z - -required: True - --- - -*`labels`*:: -+ --- -Custom key/value pairs. -Can be used to add meta information to events. Should not contain nested objects. All values are stored as keyword. -Example: `docker` and `k8s` labels. - -type: object - -example: {"application": "foo-bar", "env": "production"} - --- - -*`message`*:: -+ --- -For log events the message field contains the log message, optimized for viewing in a log viewer. -For structured logs without an original message field, other fields can be concatenated to form a human-readable summary of the event. -If multiple messages exist, they can be combined into one message. - -type: match_only_text - -example: Hello World - --- - -*`tags`*:: -+ --- -List of keywords used to tag each event. - -type: keyword - -example: ["production", "env2"] - --- - -[float] -=== agent - -The agent fields contain the data about the software entity, if any, that collects, detects, or observes events on a host, or takes measurements on a host. -Examples include Beats. Agents may also run on observers. ECS agent.* fields shall be populated with details of the agent running on the host or observer where the event happened or the measurement was taken. - - -*`agent.build.original`*:: -+ --- -Extended build information for the agent. -This field is intended to contain any build information that a data source may provide, no specific formatting is required. - -type: keyword - -example: metricbeat version 7.6.0 (amd64), libbeat 7.6.0 [6a23e8f8f30f5001ba344e4e54d8d9cb82cb107c built 2020-02-05 23:10:10 +0000 UTC] - --- - -*`agent.ephemeral_id`*:: -+ --- -Ephemeral identifier of this agent (if one exists). -This id normally changes across restarts, but `agent.id` does not. - -type: keyword - -example: 8a4f500f - --- - -*`agent.id`*:: -+ --- -Unique identifier of this agent (if one exists). -Example: For Beats this would be beat.id. - -type: keyword - -example: 8a4f500d - --- - -*`agent.name`*:: -+ --- -Custom name of the agent. -This is a name that can be given to an agent. This can be helpful if for example two Filebeat instances are running on the same host but a human readable separation is needed on which Filebeat instance data is coming from. -If no name is given, the name is often left empty. - -type: keyword - -example: foo - --- - -*`agent.type`*:: -+ --- -Type of the agent. -The agent type always stays the same and should be given by the agent used. In case of Filebeat the agent would always be Filebeat also if two Filebeat instances are run on the same machine. - -type: keyword - -example: filebeat - --- - -*`agent.version`*:: -+ --- -Version of the agent. - -type: keyword - -example: 6.0.0-rc2 - --- - -[float] -=== as - -An autonomous system (AS) is a collection of connected Internet Protocol (IP) routing prefixes under the control of one or more network operators on behalf of a single administrative entity or domain that presents a common, clearly defined routing policy to the internet. - - -*`as.number`*:: -+ --- -Unique number allocated to the autonomous system. The autonomous system number (ASN) uniquely identifies each network on the Internet. - -type: long - -example: 15169 - --- - -*`as.organization.name`*:: -+ --- -Organization name. - -type: keyword - -example: Google LLC - --- - -*`as.organization.name.text`*:: -+ --- -type: match_only_text - --- - -[float] -=== client - -A client is defined as the initiator of a network connection for events regarding sessions, connections, or bidirectional flow records. -For TCP events, the client is the initiator of the TCP connection that sends the SYN packet(s). For other protocols, the client is generally the initiator or requestor in the network transaction. Some systems use the term "originator" to refer the client in TCP connections. The client fields describe details about the system acting as the client in the network event. Client fields are usually populated in conjunction with server fields. Client fields are generally not populated for packet-level events. -Client / server representations can add semantic context to an exchange, which is helpful to visualize the data in certain situations. If your context falls in that category, you should still ensure that source and destination are filled appropriately. - - -*`client.address`*:: -+ --- -Some event client addresses are defined ambiguously. The event will sometimes list an IP, a domain or a unix socket. You should always store the raw address in the `.address` field. -Then it should be duplicated to `.ip` or `.domain`, depending on which one it is. - -type: keyword - --- - -*`client.as.number`*:: -+ --- -Unique number allocated to the autonomous system. The autonomous system number (ASN) uniquely identifies each network on the Internet. - -type: long - -example: 15169 - --- - -*`client.as.organization.name`*:: -+ --- -Organization name. - -type: keyword - -example: Google LLC - --- - -*`client.as.organization.name.text`*:: -+ --- -type: match_only_text - --- - -*`client.bytes`*:: -+ --- -Bytes sent from the client to the server. - -type: long - -example: 184 - -format: bytes - --- - -*`client.domain`*:: -+ --- -The domain name of the client system. -This value may be a host name, a fully qualified domain name, or another host naming format. The value may derive from the original event or be added from enrichment. - -type: keyword - -example: foo.example.com - --- - -*`client.geo.city_name`*:: -+ --- -City name. - -type: keyword - -example: Montreal - --- - -*`client.geo.continent_code`*:: -+ --- -Two-letter code representing continent's name. - -type: keyword - -example: NA - --- - -*`client.geo.continent_name`*:: -+ --- -Name of the continent. - -type: keyword - -example: North America - --- - -*`client.geo.country_iso_code`*:: -+ --- -Country ISO code. - -type: keyword - -example: CA - --- - -*`client.geo.country_name`*:: -+ --- -Country name. - -type: keyword - -example: Canada - --- - -*`client.geo.location`*:: -+ --- -Longitude and latitude. - -type: geo_point - -example: { "lon": -73.614830, "lat": 45.505918 } - --- - -*`client.geo.name`*:: -+ --- -User-defined description of a location, at the level of granularity they care about. -Could be the name of their data centers, the floor number, if this describes a local physical entity, city names. -Not typically used in automated geolocation. - -type: keyword - -example: boston-dc - --- - -*`client.geo.postal_code`*:: -+ --- -Postal code associated with the location. -Values appropriate for this field may also be known as a postcode or ZIP code and will vary widely from country to country. - -type: keyword - -example: 94040 - --- - -*`client.geo.region_iso_code`*:: -+ --- -Region ISO code. - -type: keyword - -example: CA-QC - --- - -*`client.geo.region_name`*:: -+ --- -Region name. - -type: keyword - -example: Quebec - --- - -*`client.geo.timezone`*:: -+ --- -The time zone of the location, such as IANA time zone name. - -type: keyword - -example: America/Argentina/Buenos_Aires - --- - -*`client.ip`*:: -+ --- -IP address of the client (IPv4 or IPv6). - -type: ip - --- - -*`client.mac`*:: -+ --- -MAC address of the client. -The notation format from RFC 7042 is suggested: Each octet (that is, 8-bit byte) is represented by two [uppercase] hexadecimal digits giving the value of the octet as an unsigned integer. Successive octets are separated by a hyphen. - -type: keyword - -example: 00-00-5E-00-53-23 - --- - -*`client.nat.ip`*:: -+ --- -Translated IP of source based NAT sessions (e.g. internal client to internet). -Typically connections traversing load balancers, firewalls, or routers. - -type: ip - --- - -*`client.nat.port`*:: -+ --- -Translated port of source based NAT sessions (e.g. internal client to internet). -Typically connections traversing load balancers, firewalls, or routers. - -type: long - -format: string - --- - -*`client.packets`*:: -+ --- -Packets sent from the client to the server. - -type: long - -example: 12 - --- - -*`client.port`*:: -+ --- -Port of the client. - -type: long - -format: string - --- - -*`client.registered_domain`*:: -+ --- -The highest registered client domain, stripped of the subdomain. -For example, the registered domain for "foo.example.com" is "example.com". -This value can be determined precisely with a list like the public suffix list (http://publicsuffix.org). Trying to approximate this by simply taking the last two labels will not work well for TLDs such as "co.uk". - -type: keyword - -example: example.com - --- - -*`client.subdomain`*:: -+ --- -The subdomain portion of a fully qualified domain name includes all of the names except the host name under the registered_domain. In a partially qualified domain, or if the the qualification level of the full name cannot be determined, subdomain contains all of the names below the registered domain. -For example the subdomain portion of "www.east.mydomain.co.uk" is "east". If the domain has multiple levels of subdomain, such as "sub2.sub1.example.com", the subdomain field should contain "sub2.sub1", with no trailing period. - -type: keyword - -example: east - --- - -*`client.top_level_domain`*:: -+ --- -The effective top level domain (eTLD), also known as the domain suffix, is the last part of the domain name. For example, the top level domain for example.com is "com". -This value can be determined precisely with a list like the public suffix list (http://publicsuffix.org). Trying to approximate this by simply taking the last label will not work well for effective TLDs such as "co.uk". - -type: keyword - -example: co.uk - --- - -*`client.user.domain`*:: -+ --- -Name of the directory the user is a member of. -For example, an LDAP or Active Directory domain name. - -type: keyword - --- - -*`client.user.email`*:: -+ --- -User email address. - -type: keyword - --- - -*`client.user.full_name`*:: -+ --- -User's full name, if available. - -type: keyword - -example: Albert Einstein - --- - -*`client.user.full_name.text`*:: -+ --- -type: match_only_text - --- - -*`client.user.group.domain`*:: -+ --- -Name of the directory the group is a member of. -For example, an LDAP or Active Directory domain name. - -type: keyword - --- - -*`client.user.group.id`*:: -+ --- -Unique identifier for the group on the system/platform. - -type: keyword - --- - -*`client.user.group.name`*:: -+ --- -Name of the group. - -type: keyword - --- - -*`client.user.hash`*:: -+ --- -Unique user hash to correlate information for a user in anonymized form. -Useful if `user.id` or `user.name` contain confidential information and cannot be used. - -type: keyword - --- - -*`client.user.id`*:: -+ --- -Unique identifier of the user. - -type: keyword - -example: S-1-5-21-202424912787-2692429404-2351956786-1000 - --- - -*`client.user.name`*:: -+ --- -Short name or login of the user. - -type: keyword - -example: a.einstein - --- - -*`client.user.name.text`*:: -+ --- -type: match_only_text - --- - -*`client.user.roles`*:: -+ --- -Array of user roles at the time of the event. - -type: keyword - -example: ["kibana_admin", "reporting_user"] - --- - -[float] -=== cloud - -Fields related to the cloud or infrastructure the events are coming from. - - -*`cloud.account.id`*:: -+ --- -The cloud account or organization id used to identify different entities in a multi-tenant environment. -Examples: AWS account id, Google Cloud ORG Id, or other unique identifier. - -type: keyword - -example: 666777888999 - --- - -*`cloud.account.name`*:: -+ --- -The cloud account name or alias used to identify different entities in a multi-tenant environment. -Examples: AWS account name, Google Cloud ORG display name. - -type: keyword - -example: elastic-dev - --- - -*`cloud.availability_zone`*:: -+ --- -Availability zone in which this host, resource, or service is located. - -type: keyword - -example: us-east-1c - --- - -*`cloud.instance.id`*:: -+ --- -Instance ID of the host machine. - -type: keyword - -example: i-1234567890abcdef0 - --- - -*`cloud.instance.name`*:: -+ --- -Instance name of the host machine. - -type: keyword - --- - -*`cloud.machine.type`*:: -+ --- -Machine type of the host machine. - -type: keyword - -example: t2.medium - --- - -*`cloud.origin.account.id`*:: -+ --- -The cloud account or organization id used to identify different entities in a multi-tenant environment. -Examples: AWS account id, Google Cloud ORG Id, or other unique identifier. - -type: keyword - -example: 666777888999 - --- - -*`cloud.origin.account.name`*:: -+ --- -The cloud account name or alias used to identify different entities in a multi-tenant environment. -Examples: AWS account name, Google Cloud ORG display name. - -type: keyword - -example: elastic-dev - --- - -*`cloud.origin.availability_zone`*:: -+ --- -Availability zone in which this host, resource, or service is located. - -type: keyword - -example: us-east-1c - --- - -*`cloud.origin.instance.id`*:: -+ --- -Instance ID of the host machine. - -type: keyword - -example: i-1234567890abcdef0 - --- - -*`cloud.origin.instance.name`*:: -+ --- -Instance name of the host machine. - -type: keyword - --- - -*`cloud.origin.machine.type`*:: -+ --- -Machine type of the host machine. - -type: keyword - -example: t2.medium - --- - -*`cloud.origin.project.id`*:: -+ --- -The cloud project identifier. -Examples: Google Cloud Project id, Azure Project id. - -type: keyword - -example: my-project - --- - -*`cloud.origin.project.name`*:: -+ --- -The cloud project name. -Examples: Google Cloud Project name, Azure Project name. - -type: keyword - -example: my project - --- - -*`cloud.origin.provider`*:: -+ --- -Name of the cloud provider. Example values are aws, azure, gcp, or digitalocean. - -type: keyword - -example: aws - --- - -*`cloud.origin.region`*:: -+ --- -Region in which this host, resource, or service is located. - -type: keyword - -example: us-east-1 - --- - -*`cloud.origin.service.name`*:: -+ --- -The cloud service name is intended to distinguish services running on different platforms within a provider, eg AWS EC2 vs Lambda, GCP GCE vs App Engine, Azure VM vs App Server. -Examples: app engine, app service, cloud run, fargate, lambda. - -type: keyword - -example: lambda - --- - -*`cloud.project.id`*:: -+ --- -The cloud project identifier. -Examples: Google Cloud Project id, Azure Project id. - -type: keyword - -example: my-project - --- - -*`cloud.project.name`*:: -+ --- -The cloud project name. -Examples: Google Cloud Project name, Azure Project name. - -type: keyword - -example: my project - --- - -*`cloud.provider`*:: -+ --- -Name of the cloud provider. Example values are aws, azure, gcp, or digitalocean. - -type: keyword - -example: aws - --- - -*`cloud.region`*:: -+ --- -Region in which this host, resource, or service is located. - -type: keyword - -example: us-east-1 - --- - -*`cloud.service.name`*:: -+ --- -The cloud service name is intended to distinguish services running on different platforms within a provider, eg AWS EC2 vs Lambda, GCP GCE vs App Engine, Azure VM vs App Server. -Examples: app engine, app service, cloud run, fargate, lambda. - -type: keyword - -example: lambda - --- - -*`cloud.target.account.id`*:: -+ --- -The cloud account or organization id used to identify different entities in a multi-tenant environment. -Examples: AWS account id, Google Cloud ORG Id, or other unique identifier. - -type: keyword - -example: 666777888999 - --- - -*`cloud.target.account.name`*:: -+ --- -The cloud account name or alias used to identify different entities in a multi-tenant environment. -Examples: AWS account name, Google Cloud ORG display name. - -type: keyword - -example: elastic-dev - --- - -*`cloud.target.availability_zone`*:: -+ --- -Availability zone in which this host, resource, or service is located. - -type: keyword - -example: us-east-1c - --- - -*`cloud.target.instance.id`*:: -+ --- -Instance ID of the host machine. - -type: keyword - -example: i-1234567890abcdef0 - --- - -*`cloud.target.instance.name`*:: -+ --- -Instance name of the host machine. - -type: keyword - --- - -*`cloud.target.machine.type`*:: -+ --- -Machine type of the host machine. - -type: keyword - -example: t2.medium - --- - -*`cloud.target.project.id`*:: -+ --- -The cloud project identifier. -Examples: Google Cloud Project id, Azure Project id. - -type: keyword - -example: my-project - --- - -*`cloud.target.project.name`*:: -+ --- -The cloud project name. -Examples: Google Cloud Project name, Azure Project name. - -type: keyword - -example: my project - --- - -*`cloud.target.provider`*:: -+ --- -Name of the cloud provider. Example values are aws, azure, gcp, or digitalocean. - -type: keyword - -example: aws - --- - -*`cloud.target.region`*:: -+ --- -Region in which this host, resource, or service is located. - -type: keyword - -example: us-east-1 - --- - -*`cloud.target.service.name`*:: -+ --- -The cloud service name is intended to distinguish services running on different platforms within a provider, eg AWS EC2 vs Lambda, GCP GCE vs App Engine, Azure VM vs App Server. -Examples: app engine, app service, cloud run, fargate, lambda. - -type: keyword - -example: lambda - --- - -[float] -=== code_signature - -These fields contain information about binary code signatures. - - -*`code_signature.digest_algorithm`*:: -+ --- -The hashing algorithm used to sign the process. -This value can distinguish signatures when a file is signed multiple times by the same signer but with a different digest algorithm. - -type: keyword - -example: sha256 - --- - -*`code_signature.exists`*:: -+ --- -Boolean to capture if a signature is present. - -type: boolean - -example: true - --- - -*`code_signature.signing_id`*:: -+ --- -The identifier used to sign the process. -This is used to identify the application manufactured by a software vendor. The field is relevant to Apple *OS only. - -type: keyword - -example: com.apple.xpc.proxy - --- - -*`code_signature.status`*:: -+ --- -Additional information about the certificate status. -This is useful for logging cryptographic errors with the certificate validity or trust status. Leave unpopulated if the validity or trust of the certificate was unchecked. - -type: keyword - -example: ERROR_UNTRUSTED_ROOT - --- - -*`code_signature.subject_name`*:: -+ --- -Subject name of the code signer - -type: keyword - -example: Microsoft Corporation - --- - -*`code_signature.team_id`*:: -+ --- -The team identifier used to sign the process. -This is used to identify the team or vendor of a software product. The field is relevant to Apple *OS only. - -type: keyword - -example: EQHXZ8M8AV - --- - -*`code_signature.timestamp`*:: -+ --- -Date and time when the code signature was generated and signed. - -type: date - -example: 2021-01-01T12:10:30Z - --- - -*`code_signature.trusted`*:: -+ --- -Stores the trust status of the certificate chain. -Validating the trust of the certificate chain may be complicated, and this field should only be populated by tools that actively check the status. - -type: boolean - -example: true - --- - -*`code_signature.valid`*:: -+ --- -Boolean to capture if the digital signature is verified against the binary content. -Leave unpopulated if a certificate was unchecked. - -type: boolean - -example: true - --- - -[float] -=== container - -Container fields are used for meta information about the specific container that is the source of information. These fields help correlate data based containers from any runtime. - - -*`container.cpu.usage`*:: -+ --- -Percent CPU used which is normalized by the number of CPU cores and it ranges from 0 to 1. Scaling factor: 1000. - -type: scaled_float - --- - -*`container.disk.read.bytes`*:: -+ --- -The total number of bytes (gauge) read successfully (aggregated from all disks) since the last metric collection. - -type: long - --- - -*`container.disk.write.bytes`*:: -+ --- -The total number of bytes (gauge) written successfully (aggregated from all disks) since the last metric collection. - -type: long - --- - -*`container.id`*:: -+ --- -Unique container id. - -type: keyword - --- - -*`container.image.name`*:: -+ --- -Name of the image the container was built on. - -type: keyword - --- - -*`container.image.tag`*:: -+ --- -Container image tags. - -type: keyword - --- - -*`container.labels`*:: -+ --- -Image labels. - -type: object - --- - -*`container.memory.usage`*:: -+ --- -Memory usage percentage and it ranges from 0 to 1. Scaling factor: 1000. - -type: scaled_float - --- - -*`container.name`*:: -+ --- -Container name. - -type: keyword - --- - -*`container.network.egress.bytes`*:: -+ --- -The number of bytes (gauge) sent out on all network interfaces by the container since the last metric collection. - -type: long - --- - -*`container.network.ingress.bytes`*:: -+ --- -The number of bytes received (gauge) on all network interfaces by the container since the last metric collection. - -type: long - --- - -*`container.runtime`*:: -+ --- -Runtime managing this container. - -type: keyword - -example: docker - --- - -[float] -=== data_stream - -The data_stream fields take part in defining the new data stream naming scheme. -In the new data stream naming scheme the value of the data stream fields combine to the name of the actual data stream in the following manner: `{data_stream.type}-{data_stream.dataset}-{data_stream.namespace}`. This means the fields can only contain characters that are valid as part of names of data streams. More details about this can be found in this https://www.elastic.co/blog/an-introduction-to-the-elastic-data-stream-naming-scheme[blog post]. -An Elasticsearch data stream consists of one or more backing indices, and a data stream name forms part of the backing indices names. Due to this convention, data streams must also follow index naming restrictions. For example, data stream names cannot include `\`, `/`, `*`, `?`, `"`, `<`, `>`, `|`, ` ` (space character), `,`, or `#`. Please see the Elasticsearch reference for additional https://www.elastic.co/guide/en/elasticsearch/reference/current/indices-create-index.html#indices-create-api-path-params[restrictions]. - - -*`data_stream.dataset`*:: -+ --- -The field can contain anything that makes sense to signify the source of the data. -Examples include `nginx.access`, `prometheus`, `endpoint` etc. For data streams that otherwise fit, but that do not have dataset set we use the value "generic" for the dataset value. `event.dataset` should have the same value as `data_stream.dataset`. -Beyond the Elasticsearch data stream naming criteria noted above, the `dataset` value has additional restrictions: - * Must not contain `-` - * No longer than 100 characters - -type: constant_keyword - -example: nginx.access - --- - -*`data_stream.namespace`*:: -+ --- -A user defined namespace. Namespaces are useful to allow grouping of data. -Many users already organize their indices this way, and the data stream naming scheme now provides this best practice as a default. Many users will populate this field with `default`. If no value is used, it falls back to `default`. -Beyond the Elasticsearch index naming criteria noted above, `namespace` value has the additional restrictions: - * Must not contain `-` - * No longer than 100 characters - -type: constant_keyword - -example: production - --- - -*`data_stream.type`*:: -+ --- -An overarching type for the data stream. -Currently allowed values are "logs" and "metrics". We expect to also add "traces" and "synthetics" in the near future. - -type: constant_keyword - -example: logs - --- - -[float] -=== destination - -Destination fields capture details about the receiver of a network exchange/packet. These fields are populated from a network event, packet, or other event containing details of a network transaction. -Destination fields are usually populated in conjunction with source fields. The source and destination fields are considered the baseline and should always be filled if an event contains source and destination details from a network transaction. If the event also contains identification of the client and server roles, then the client and server fields should also be populated. - - -*`destination.address`*:: -+ --- -Some event destination addresses are defined ambiguously. The event will sometimes list an IP, a domain or a unix socket. You should always store the raw address in the `.address` field. -Then it should be duplicated to `.ip` or `.domain`, depending on which one it is. - -type: keyword - --- - -*`destination.as.number`*:: -+ --- -Unique number allocated to the autonomous system. The autonomous system number (ASN) uniquely identifies each network on the Internet. - -type: long - -example: 15169 - --- - -*`destination.as.organization.name`*:: -+ --- -Organization name. - -type: keyword - -example: Google LLC - --- - -*`destination.as.organization.name.text`*:: -+ --- -type: match_only_text - --- - -*`destination.bytes`*:: -+ --- -Bytes sent from the destination to the source. - -type: long - -example: 184 - -format: bytes - --- - -*`destination.domain`*:: -+ --- -The domain name of the destination system. -This value may be a host name, a fully qualified domain name, or another host naming format. The value may derive from the original event or be added from enrichment. - -type: keyword - -example: foo.example.com - --- - -*`destination.geo.city_name`*:: -+ --- -City name. - -type: keyword - -example: Montreal - --- - -*`destination.geo.continent_code`*:: -+ --- -Two-letter code representing continent's name. - -type: keyword - -example: NA - --- - -*`destination.geo.continent_name`*:: -+ --- -Name of the continent. - -type: keyword - -example: North America - --- - -*`destination.geo.country_iso_code`*:: -+ --- -Country ISO code. - -type: keyword - -example: CA - --- - -*`destination.geo.country_name`*:: -+ --- -Country name. - -type: keyword - -example: Canada - --- - -*`destination.geo.location`*:: -+ --- -Longitude and latitude. - -type: geo_point - -example: { "lon": -73.614830, "lat": 45.505918 } - --- - -*`destination.geo.name`*:: -+ --- -User-defined description of a location, at the level of granularity they care about. -Could be the name of their data centers, the floor number, if this describes a local physical entity, city names. -Not typically used in automated geolocation. - -type: keyword - -example: boston-dc - --- - -*`destination.geo.postal_code`*:: -+ --- -Postal code associated with the location. -Values appropriate for this field may also be known as a postcode or ZIP code and will vary widely from country to country. - -type: keyword - -example: 94040 - --- - -*`destination.geo.region_iso_code`*:: -+ --- -Region ISO code. - -type: keyword - -example: CA-QC - --- - -*`destination.geo.region_name`*:: -+ --- -Region name. - -type: keyword - -example: Quebec - --- - -*`destination.geo.timezone`*:: -+ --- -The time zone of the location, such as IANA time zone name. - -type: keyword - -example: America/Argentina/Buenos_Aires - --- - -*`destination.ip`*:: -+ --- -IP address of the destination (IPv4 or IPv6). - -type: ip - --- - -*`destination.mac`*:: -+ --- -MAC address of the destination. -The notation format from RFC 7042 is suggested: Each octet (that is, 8-bit byte) is represented by two [uppercase] hexadecimal digits giving the value of the octet as an unsigned integer. Successive octets are separated by a hyphen. - -type: keyword - -example: 00-00-5E-00-53-23 - --- - -*`destination.nat.ip`*:: -+ --- -Translated ip of destination based NAT sessions (e.g. internet to private DMZ) -Typically used with load balancers, firewalls, or routers. - -type: ip - --- - -*`destination.nat.port`*:: -+ --- -Port the source session is translated to by NAT Device. -Typically used with load balancers, firewalls, or routers. - -type: long - -format: string - --- - -*`destination.packets`*:: -+ --- -Packets sent from the destination to the source. - -type: long - -example: 12 - --- - -*`destination.port`*:: -+ --- -Port of the destination. - -type: long - -format: string - --- - -*`destination.registered_domain`*:: -+ --- -The highest registered destination domain, stripped of the subdomain. -For example, the registered domain for "foo.example.com" is "example.com". -This value can be determined precisely with a list like the public suffix list (http://publicsuffix.org). Trying to approximate this by simply taking the last two labels will not work well for TLDs such as "co.uk". - -type: keyword - -example: example.com - --- - -*`destination.subdomain`*:: -+ --- -The subdomain portion of a fully qualified domain name includes all of the names except the host name under the registered_domain. In a partially qualified domain, or if the the qualification level of the full name cannot be determined, subdomain contains all of the names below the registered domain. -For example the subdomain portion of "www.east.mydomain.co.uk" is "east". If the domain has multiple levels of subdomain, such as "sub2.sub1.example.com", the subdomain field should contain "sub2.sub1", with no trailing period. - -type: keyword - -example: east - --- - -*`destination.top_level_domain`*:: -+ --- -The effective top level domain (eTLD), also known as the domain suffix, is the last part of the domain name. For example, the top level domain for example.com is "com". -This value can be determined precisely with a list like the public suffix list (http://publicsuffix.org). Trying to approximate this by simply taking the last label will not work well for effective TLDs such as "co.uk". - -type: keyword - -example: co.uk - --- - -*`destination.user.domain`*:: -+ --- -Name of the directory the user is a member of. -For example, an LDAP or Active Directory domain name. - -type: keyword - --- - -*`destination.user.email`*:: -+ --- -User email address. - -type: keyword - --- - -*`destination.user.full_name`*:: -+ --- -User's full name, if available. - -type: keyword - -example: Albert Einstein - --- - -*`destination.user.full_name.text`*:: -+ --- -type: match_only_text - --- - -*`destination.user.group.domain`*:: -+ --- -Name of the directory the group is a member of. -For example, an LDAP or Active Directory domain name. - -type: keyword - --- - -*`destination.user.group.id`*:: -+ --- -Unique identifier for the group on the system/platform. - -type: keyword - --- - -*`destination.user.group.name`*:: -+ --- -Name of the group. - -type: keyword - --- - -*`destination.user.hash`*:: -+ --- -Unique user hash to correlate information for a user in anonymized form. -Useful if `user.id` or `user.name` contain confidential information and cannot be used. - -type: keyword - --- - -*`destination.user.id`*:: -+ --- -Unique identifier of the user. - -type: keyword - -example: S-1-5-21-202424912787-2692429404-2351956786-1000 - --- - -*`destination.user.name`*:: -+ --- -Short name or login of the user. - -type: keyword - -example: a.einstein - --- - -*`destination.user.name.text`*:: -+ --- -type: match_only_text - --- - -*`destination.user.roles`*:: -+ --- -Array of user roles at the time of the event. - -type: keyword - -example: ["kibana_admin", "reporting_user"] - --- - -[float] -=== dll - -These fields contain information about code libraries dynamically loaded into processes. - -Many operating systems refer to "shared code libraries" with different names, but this field set refers to all of the following: -* Dynamic-link library (`.dll`) commonly used on Windows -* Shared Object (`.so`) commonly used on Unix-like operating systems -* Dynamic library (`.dylib`) commonly used on macOS - - -*`dll.code_signature.digest_algorithm`*:: -+ --- -The hashing algorithm used to sign the process. -This value can distinguish signatures when a file is signed multiple times by the same signer but with a different digest algorithm. - -type: keyword - -example: sha256 - --- - -*`dll.code_signature.exists`*:: -+ --- -Boolean to capture if a signature is present. - -type: boolean - -example: true - --- - -*`dll.code_signature.signing_id`*:: -+ --- -The identifier used to sign the process. -This is used to identify the application manufactured by a software vendor. The field is relevant to Apple *OS only. - -type: keyword - -example: com.apple.xpc.proxy - --- - -*`dll.code_signature.status`*:: -+ --- -Additional information about the certificate status. -This is useful for logging cryptographic errors with the certificate validity or trust status. Leave unpopulated if the validity or trust of the certificate was unchecked. - -type: keyword - -example: ERROR_UNTRUSTED_ROOT - --- - -*`dll.code_signature.subject_name`*:: -+ --- -Subject name of the code signer - -type: keyword - -example: Microsoft Corporation - --- - -*`dll.code_signature.team_id`*:: -+ --- -The team identifier used to sign the process. -This is used to identify the team or vendor of a software product. The field is relevant to Apple *OS only. - -type: keyword - -example: EQHXZ8M8AV - --- - -*`dll.code_signature.timestamp`*:: -+ --- -Date and time when the code signature was generated and signed. - -type: date - -example: 2021-01-01T12:10:30Z - --- - -*`dll.code_signature.trusted`*:: -+ --- -Stores the trust status of the certificate chain. -Validating the trust of the certificate chain may be complicated, and this field should only be populated by tools that actively check the status. - -type: boolean - -example: true - --- - -*`dll.code_signature.valid`*:: -+ --- -Boolean to capture if the digital signature is verified against the binary content. -Leave unpopulated if a certificate was unchecked. - -type: boolean - -example: true - --- - -*`dll.hash.md5`*:: -+ --- -MD5 hash. - -type: keyword - --- - -*`dll.hash.sha1`*:: -+ --- -SHA1 hash. - -type: keyword - --- - -*`dll.hash.sha256`*:: -+ --- -SHA256 hash. - -type: keyword - --- - -*`dll.hash.sha512`*:: -+ --- -SHA512 hash. - -type: keyword - --- - -*`dll.hash.ssdeep`*:: -+ --- -SSDEEP hash. - -type: keyword - --- - -*`dll.name`*:: -+ --- -Name of the library. -This generally maps to the name of the file on disk. - -type: keyword - -example: kernel32.dll - --- - -*`dll.path`*:: -+ --- -Full file path of the library. - -type: keyword - -example: C:\Windows\System32\kernel32.dll - --- - -*`dll.pe.architecture`*:: -+ --- -CPU architecture target for the file. - -type: keyword - -example: x64 - --- - -*`dll.pe.company`*:: -+ --- -Internal company name of the file, provided at compile-time. - -type: keyword - -example: Microsoft Corporation - --- - -*`dll.pe.description`*:: -+ --- -Internal description of the file, provided at compile-time. - -type: keyword - -example: Paint - --- - -*`dll.pe.file_version`*:: -+ --- -Internal version of the file, provided at compile-time. - -type: keyword - -example: 6.3.9600.17415 - --- - -*`dll.pe.imphash`*:: -+ --- -A hash of the imports in a PE file. An imphash -- or import hash -- can be used to fingerprint binaries even after recompilation or other code-level transformations have occurred, which would change more traditional hash values. -Learn more at https://www.fireeye.com/blog/threat-research/2014/01/tracking-malware-import-hashing.html. - -type: keyword - -example: 0c6803c4e922103c4dca5963aad36ddf - --- - -*`dll.pe.original_file_name`*:: -+ --- -Internal name of the file, provided at compile-time. - -type: keyword - -example: MSPAINT.EXE - --- - -*`dll.pe.product`*:: -+ --- -Internal product name of the file, provided at compile-time. - -type: keyword - -example: Microsoft® Windows® Operating System - --- - -[float] -=== dns - -Fields describing DNS queries and answers. -DNS events should either represent a single DNS query prior to getting answers (`dns.type:query`) or they should represent a full exchange and contain the query details as well as all of the answers that were provided for this query (`dns.type:answer`). - - -*`dns.answers`*:: -+ --- -An array containing an object for each answer section returned by the server. -The main keys that should be present in these objects are defined by ECS. Records that have more information may contain more keys than what ECS defines. -Not all DNS data sources give all details about DNS answers. At minimum, answer objects must contain the `data` key. If more information is available, map as much of it to ECS as possible, and add any additional fields to the answer objects as custom fields. - -type: object - --- - -*`dns.answers.class`*:: -+ --- -The class of DNS data contained in this resource record. - -type: keyword - -example: IN - --- - -*`dns.answers.data`*:: -+ --- -The data describing the resource. -The meaning of this data depends on the type and class of the resource record. - -type: keyword - -example: 10.10.10.10 - --- - -*`dns.answers.name`*:: -+ --- -The domain name to which this resource record pertains. -If a chain of CNAME is being resolved, each answer's `name` should be the one that corresponds with the answer's `data`. It should not simply be the original `question.name` repeated. - -type: keyword - -example: www.example.com - --- - -*`dns.answers.ttl`*:: -+ --- -The time interval in seconds that this resource record may be cached before it should be discarded. Zero values mean that the data should not be cached. - -type: long - -example: 180 - --- - -*`dns.answers.type`*:: -+ --- -The type of data contained in this resource record. - -type: keyword - -example: CNAME - --- - -*`dns.header_flags`*:: -+ --- -Array of 2 letter DNS header flags. -Expected values are: AA, TC, RD, RA, AD, CD, DO. - -type: keyword - -example: ["RD", "RA"] - --- - -*`dns.id`*:: -+ --- -The DNS packet identifier assigned by the program that generated the query. The identifier is copied to the response. - -type: keyword - -example: 62111 - --- - -*`dns.op_code`*:: -+ --- -The DNS operation code that specifies the kind of query in the message. This value is set by the originator of a query and copied into the response. - -type: keyword - -example: QUERY - --- - -*`dns.question.class`*:: -+ --- -The class of records being queried. - -type: keyword - -example: IN - --- - -*`dns.question.name`*:: -+ --- -The name being queried. -If the name field contains non-printable characters (below 32 or above 126), those characters should be represented as escaped base 10 integers (\DDD). Back slashes and quotes should be escaped. Tabs, carriage returns, and line feeds should be converted to \t, \r, and \n respectively. - -type: keyword - -example: www.example.com - --- - -*`dns.question.registered_domain`*:: -+ --- -The highest registered domain, stripped of the subdomain. -For example, the registered domain for "foo.example.com" is "example.com". -This value can be determined precisely with a list like the public suffix list (http://publicsuffix.org). Trying to approximate this by simply taking the last two labels will not work well for TLDs such as "co.uk". - -type: keyword - -example: example.com - --- - -*`dns.question.subdomain`*:: -+ --- -The subdomain is all of the labels under the registered_domain. -If the domain has multiple levels of subdomain, such as "sub2.sub1.example.com", the subdomain field should contain "sub2.sub1", with no trailing period. - -type: keyword - -example: www - --- - -*`dns.question.top_level_domain`*:: -+ --- -The effective top level domain (eTLD), also known as the domain suffix, is the last part of the domain name. For example, the top level domain for example.com is "com". -This value can be determined precisely with a list like the public suffix list (http://publicsuffix.org). Trying to approximate this by simply taking the last label will not work well for effective TLDs such as "co.uk". - -type: keyword - -example: co.uk - --- - -*`dns.question.type`*:: -+ --- -The type of record being queried. - -type: keyword - -example: AAAA - --- - -*`dns.resolved_ip`*:: -+ --- -Array containing all IPs seen in `answers.data`. -The `answers` array can be difficult to use, because of the variety of data formats it can contain. Extracting all IP addresses seen in there to `dns.resolved_ip` makes it possible to index them as IP addresses, and makes them easier to visualize and query for. - -type: ip - -example: ["10.10.10.10", "10.10.10.11"] - --- - -*`dns.response_code`*:: -+ --- -The DNS response code. - -type: keyword - -example: NOERROR - --- - -*`dns.type`*:: -+ --- -The type of DNS event captured, query or answer. -If your source of DNS events only gives you DNS queries, you should only create dns events of type `dns.type:query`. -If your source of DNS events gives you answers as well, you should create one event per query (optionally as soon as the query is seen). And a second event containing all query details as well as an array of answers. - -type: keyword - -example: answer - --- - -[float] -=== ecs - -Meta-information specific to ECS. - - -*`ecs.version`*:: -+ --- -ECS version this event conforms to. `ecs.version` is a required field and must exist in all events. -When querying across multiple indices -- which may conform to slightly different ECS versions -- this field lets integrations adjust to the schema version of the events. - -type: keyword - -example: 1.0.0 - -required: True - --- - -[float] -=== elf - -These fields contain Linux Executable Linkable Format (ELF) metadata. - - -*`elf.architecture`*:: -+ --- -Machine architecture of the ELF file. - -type: keyword - -example: x86-64 - --- - -*`elf.byte_order`*:: -+ --- -Byte sequence of ELF file. - -type: keyword - -example: Little Endian - --- - -*`elf.cpu_type`*:: -+ --- -CPU type of the ELF file. - -type: keyword - -example: Intel - --- - -*`elf.creation_date`*:: -+ --- -Extracted when possible from the file's metadata. Indicates when it was built or compiled. It can also be faked by malware creators. - -type: date - --- - -*`elf.exports`*:: -+ --- -List of exported element names and types. - -type: flattened - --- - -*`elf.header.abi_version`*:: -+ --- -Version of the ELF Application Binary Interface (ABI). - -type: keyword - --- - -*`elf.header.class`*:: -+ --- -Header class of the ELF file. - -type: keyword - --- - -*`elf.header.data`*:: -+ --- -Data table of the ELF header. - -type: keyword - --- - -*`elf.header.entrypoint`*:: -+ --- -Header entrypoint of the ELF file. - -type: long - -format: string - --- - -*`elf.header.object_version`*:: -+ --- -"0x1" for original ELF files. - -type: keyword - --- - -*`elf.header.os_abi`*:: -+ --- -Application Binary Interface (ABI) of the Linux OS. - -type: keyword - --- - -*`elf.header.type`*:: -+ --- -Header type of the ELF file. - -type: keyword - --- - -*`elf.header.version`*:: -+ --- -Version of the ELF header. - -type: keyword - --- - -*`elf.imports`*:: -+ --- -List of imported element names and types. - -type: flattened - --- - -*`elf.sections`*:: -+ --- -An array containing an object for each section of the ELF file. -The keys that should be present in these objects are defined by sub-fields underneath `elf.sections.*`. - -type: nested - --- - -*`elf.sections.chi2`*:: -+ --- -Chi-square probability distribution of the section. - -type: long - -format: number - --- - -*`elf.sections.entropy`*:: -+ --- -Shannon entropy calculation from the section. - -type: long - -format: number - --- - -*`elf.sections.flags`*:: -+ --- -ELF Section List flags. - -type: keyword - --- - -*`elf.sections.name`*:: -+ --- -ELF Section List name. - -type: keyword - --- - -*`elf.sections.physical_offset`*:: -+ --- -ELF Section List offset. - -type: keyword - --- - -*`elf.sections.physical_size`*:: -+ --- -ELF Section List physical size. - -type: long - -format: bytes - --- - -*`elf.sections.type`*:: -+ --- -ELF Section List type. - -type: keyword - --- - -*`elf.sections.virtual_address`*:: -+ --- -ELF Section List virtual address. - -type: long - -format: string - --- - -*`elf.sections.virtual_size`*:: -+ --- -ELF Section List virtual size. - -type: long - -format: string - --- - -*`elf.segments`*:: -+ --- -An array containing an object for each segment of the ELF file. -The keys that should be present in these objects are defined by sub-fields underneath `elf.segments.*`. - -type: nested - --- - -*`elf.segments.sections`*:: -+ --- -ELF object segment sections. - -type: keyword - --- - -*`elf.segments.type`*:: -+ --- -ELF object segment type. - -type: keyword - --- - -*`elf.shared_libraries`*:: -+ --- -List of shared libraries used by this ELF object. - -type: keyword - --- - -*`elf.telfhash`*:: -+ --- -telfhash symbol hash for ELF file. - -type: keyword - --- - -[float] -=== error - -These fields can represent errors of any kind. -Use them for errors that happen while fetching events or in cases where the event itself contains an error. - - -*`error.code`*:: -+ --- -Error code describing the error. - -type: keyword - --- - -*`error.id`*:: -+ --- -Unique identifier for the error. - -type: keyword - --- - -*`error.message`*:: -+ --- -Error message. - -type: match_only_text - --- - -*`error.stack_trace`*:: -+ --- -The stack trace of this error in plain text. - -type: wildcard - --- - -*`error.stack_trace.text`*:: -+ --- -type: match_only_text - --- - -*`error.type`*:: -+ --- -The type of the error, for example the class name of the exception. - -type: keyword - -example: java.lang.NullPointerException - --- - -[float] -=== event - -The event fields are used for context information about the log or metric event itself. -A log is defined as an event containing details of something that happened. Log events must include the time at which the thing happened. Examples of log events include a process starting on a host, a network packet being sent from a source to a destination, or a network connection between a client and a server being initiated or closed. A metric is defined as an event containing one or more numerical measurements and the time at which the measurement was taken. Examples of metric events include memory pressure measured on a host and device temperature. See the `event.kind` definition in this section for additional details about metric and state events. - - -*`event.action`*:: -+ --- -The action captured by the event. -This describes the information in the event. It is more specific than `event.category`. Examples are `group-add`, `process-started`, `file-created`. The value is normally defined by the implementer. - -type: keyword - -example: user-password-change - --- - -*`event.agent_id_status`*:: -+ --- -Agents are normally responsible for populating the `agent.id` field value. If the system receiving events is capable of validating the value based on authentication information for the client then this field can be used to reflect the outcome of that validation. -For example if the agent's connection is authenticated with mTLS and the client cert contains the ID of the agent to which the cert was issued then the `agent.id` value in events can be checked against the certificate. If the values match then `event.agent_id_status: verified` is added to the event, otherwise one of the other allowed values should be used. -If no validation is performed then the field should be omitted. -The allowed values are: -`verified` - The `agent.id` field value matches expected value obtained from auth metadata. -`mismatch` - The `agent.id` field value does not match the expected value obtained from auth metadata. -`missing` - There was no `agent.id` field in the event to validate. -`auth_metadata_missing` - There was no auth metadata or it was missing information about the agent ID. - -type: keyword - -example: verified - --- - -*`event.category`*:: -+ --- -This is one of four ECS Categorization Fields, and indicates the second level in the ECS category hierarchy. -`event.category` represents the "big buckets" of ECS categories. For example, filtering on `event.category:process` yields all events relating to process activity. This field is closely related to `event.type`, which is used as a subcategory. -This field is an array. This will allow proper categorization of some events that fall in multiple categories. - -type: keyword - -example: authentication - --- - -*`event.code`*:: -+ --- -Identification code for this event, if one exists. -Some event sources use event codes to identify messages unambiguously, regardless of message language or wording adjustments over time. An example of this is the Windows Event ID. - -type: keyword - -example: 4648 - --- - -*`event.created`*:: -+ --- -event.created contains the date/time when the event was first read by an agent, or by your pipeline. -This field is distinct from @timestamp in that @timestamp typically contain the time extracted from the original event. -In most situations, these two timestamps will be slightly different. The difference can be used to calculate the delay between your source generating an event, and the time when your agent first processed it. This can be used to monitor your agent's or pipeline's ability to keep up with your event source. -In case the two timestamps are identical, @timestamp should be used. - -type: date - -example: 2016-05-23T08:05:34.857Z - --- - -*`event.dataset`*:: -+ --- -Name of the dataset. -If an event source publishes more than one type of log or events (e.g. access log, error log), the dataset is used to specify which one the event comes from. -It's recommended but not required to start the dataset name with the module name, followed by a dot, then the dataset name. - -type: keyword - -example: apache.access - --- - -*`event.duration`*:: -+ --- -Duration of the event in nanoseconds. -If event.start and event.end are known this value should be the difference between the end and start time. - -type: long - -format: duration - --- - -*`event.end`*:: -+ --- -event.end contains the date when the event ended or when the activity was last observed. - -type: date - --- - -*`event.hash`*:: -+ --- -Hash (perhaps logstash fingerprint) of raw field to be able to demonstrate log integrity. - -type: keyword - -example: 123456789012345678901234567890ABCD - --- - -*`event.id`*:: -+ --- -Unique ID to describe the event. - -type: keyword - -example: 8a4f500d - --- - -*`event.ingested`*:: -+ --- -Timestamp when an event arrived in the central data store. -This is different from `@timestamp`, which is when the event originally occurred. It's also different from `event.created`, which is meant to capture the first time an agent saw the event. -In normal conditions, assuming no tampering, the timestamps should chronologically look like this: `@timestamp` < `event.created` < `event.ingested`. - -type: date - -example: 2016-05-23T08:05:35.101Z - --- - -*`event.kind`*:: -+ --- -This is one of four ECS Categorization Fields, and indicates the highest level in the ECS category hierarchy. -`event.kind` gives high-level information about what type of information the event contains, without being specific to the contents of the event. For example, values of this field distinguish alert events from metric events. -The value of this field can be used to inform how these kinds of events should be handled. They may warrant different retention, different access control, it may also help understand whether the data coming in at a regular interval or not. - -type: keyword - -example: alert - --- - -*`event.module`*:: -+ --- -Name of the module this data is coming from. -If your monitoring agent supports the concept of modules or plugins to process events of a given source (e.g. Apache logs), `event.module` should contain the name of this module. - -type: keyword - -example: apache - --- - -*`event.original`*:: -+ --- -Raw text message of entire event. Used to demonstrate log integrity or where the full log message (before splitting it up in multiple parts) may be required, e.g. for reindex. -This field is not indexed and doc_values are disabled. It cannot be searched, but it can be retrieved from `_source`. If users wish to override this and index this field, please see `Field data types` in the `Elasticsearch Reference`. - -type: keyword - -example: Sep 19 08:26:10 host CEF:0|Security| threatmanager|1.0|100| worm successfully stopped|10|src=10.0.0.1 dst=2.1.2.2spt=1232 - -Field is not indexed. - --- - -*`event.outcome`*:: -+ --- -This is one of four ECS Categorization Fields, and indicates the lowest level in the ECS category hierarchy. -`event.outcome` simply denotes whether the event represents a success or a failure from the perspective of the entity that produced the event. -Note that when a single transaction is described in multiple events, each event may populate different values of `event.outcome`, according to their perspective. -Also note that in the case of a compound event (a single event that contains multiple logical events), this field should be populated with the value that best captures the overall success or failure from the perspective of the event producer. -Further note that not all events will have an associated outcome. For example, this field is generally not populated for metric events, events with `event.type:info`, or any events for which an outcome does not make logical sense. - -type: keyword - -example: success - --- - -*`event.provider`*:: -+ --- -Source of the event. -Event transports such as Syslog or the Windows Event Log typically mention the source of an event. It can be the name of the software that generated the event (e.g. Sysmon, httpd), or of a subsystem of the operating system (kernel, Microsoft-Windows-Security-Auditing). - -type: keyword - -example: kernel - --- - -*`event.reason`*:: -+ --- -Reason why this event happened, according to the source. -This describes the why of a particular action or outcome captured in the event. Where `event.action` captures the action from the event, `event.reason` describes why that action was taken. For example, a web proxy with an `event.action` which denied the request may also populate `event.reason` with the reason why (e.g. `blocked site`). - -type: keyword - -example: Terminated an unexpected process - --- - -*`event.reference`*:: -+ --- -Reference URL linking to additional information about this event. -This URL links to a static definition of this event. Alert events, indicated by `event.kind:alert`, are a common use case for this field. - -type: keyword - -example: https://system.example.com/event/#0001234 - --- - -*`event.risk_score`*:: -+ --- -Risk score or priority of the event (e.g. security solutions). Use your system's original value here. - -type: float - --- - -*`event.risk_score_norm`*:: -+ --- -Normalized risk score or priority of the event, on a scale of 0 to 100. -This is mainly useful if you use more than one system that assigns risk scores, and you want to see a normalized value across all systems. - -type: float - --- - -*`event.sequence`*:: -+ --- -Sequence number of the event. -The sequence number is a value published by some event sources, to make the exact ordering of events unambiguous, regardless of the timestamp precision. - -type: long - -format: string - --- - -*`event.severity`*:: -+ --- -The numeric severity of the event according to your event source. -What the different severity values mean can be different between sources and use cases. It's up to the implementer to make sure severities are consistent across events from the same source. -The Syslog severity belongs in `log.syslog.severity.code`. `event.severity` is meant to represent the severity according to the event source (e.g. firewall, IDS). If the event source does not publish its own severity, you may optionally copy the `log.syslog.severity.code` to `event.severity`. - -type: long - -example: 7 - -format: string - --- - -*`event.start`*:: -+ --- -event.start contains the date when the event started or when the activity was first observed. - -type: date - --- - -*`event.timezone`*:: -+ --- -This field should be populated when the event's timestamp does not include timezone information already (e.g. default Syslog timestamps). It's optional otherwise. -Acceptable timezone formats are: a canonical ID (e.g. "Europe/Amsterdam"), abbreviated (e.g. "EST") or an HH:mm differential (e.g. "-05:00"). - -type: keyword - --- - -*`event.type`*:: -+ --- -This is one of four ECS Categorization Fields, and indicates the third level in the ECS category hierarchy. -`event.type` represents a categorization "sub-bucket" that, when used along with the `event.category` field values, enables filtering events down to a level appropriate for single visualization. -This field is an array. This will allow proper categorization of some events that fall in multiple event types. - -type: keyword - --- - -*`event.url`*:: -+ --- -URL linking to an external system to continue investigation of this event. -This URL links to another system where in-depth investigation of the specific occurrence of this event can take place. Alert events, indicated by `event.kind:alert`, are a common use case for this field. - -type: keyword - -example: https://mysystem.example.com/alert/5271dedb-f5b0-4218-87f0-4ac4870a38fe - --- - -[float] -=== faas - -The user fields describe information about the function as a service that is relevant to the event. - - -*`faas.coldstart`*:: -+ --- -Boolean value indicating a cold start of a function. - -type: boolean - --- - -*`faas.execution`*:: -+ --- -The execution ID of the current function execution. - -type: keyword - -example: af9d5aa4-a685-4c5f-a22b-444f80b3cc28 - --- - -*`faas.trigger`*:: -+ --- -Details about the function trigger. - -type: nested - --- - -*`faas.trigger.request_id`*:: -+ --- -The ID of the trigger request , message, event, etc. - -type: keyword - -example: 123456789 - --- - -*`faas.trigger.type`*:: -+ --- -The trigger for the function execution. -Expected values are: - * http - * pubsub - * datasource - * timer - * other - -type: keyword - -example: http - --- - -[float] -=== file - -A file is defined as a set of information that has been created on, or has existed on a filesystem. -File objects can be associated with host events, network events, and/or file events (e.g., those produced by File Integrity Monitoring [FIM] products or services). File fields provide details about the affected file associated with the event or metric. - - -*`file.accessed`*:: -+ --- -Last time the file was accessed. -Note that not all filesystems keep track of access time. - -type: date - --- - -*`file.attributes`*:: -+ --- -Array of file attributes. -Attributes names will vary by platform. Here's a non-exhaustive list of values that are expected in this field: archive, compressed, directory, encrypted, execute, hidden, read, readonly, system, write. - -type: keyword - -example: ["readonly", "system"] - --- - -*`file.code_signature.digest_algorithm`*:: -+ --- -The hashing algorithm used to sign the process. -This value can distinguish signatures when a file is signed multiple times by the same signer but with a different digest algorithm. - -type: keyword - -example: sha256 - --- - -*`file.code_signature.exists`*:: -+ --- -Boolean to capture if a signature is present. - -type: boolean - -example: true - --- - -*`file.code_signature.signing_id`*:: -+ --- -The identifier used to sign the process. -This is used to identify the application manufactured by a software vendor. The field is relevant to Apple *OS only. - -type: keyword - -example: com.apple.xpc.proxy - --- - -*`file.code_signature.status`*:: -+ --- -Additional information about the certificate status. -This is useful for logging cryptographic errors with the certificate validity or trust status. Leave unpopulated if the validity or trust of the certificate was unchecked. - -type: keyword - -example: ERROR_UNTRUSTED_ROOT - --- - -*`file.code_signature.subject_name`*:: -+ --- -Subject name of the code signer - -type: keyword - -example: Microsoft Corporation - --- - -*`file.code_signature.team_id`*:: -+ --- -The team identifier used to sign the process. -This is used to identify the team or vendor of a software product. The field is relevant to Apple *OS only. - -type: keyword - -example: EQHXZ8M8AV - --- - -*`file.code_signature.timestamp`*:: -+ --- -Date and time when the code signature was generated and signed. - -type: date - -example: 2021-01-01T12:10:30Z - --- - -*`file.code_signature.trusted`*:: -+ --- -Stores the trust status of the certificate chain. -Validating the trust of the certificate chain may be complicated, and this field should only be populated by tools that actively check the status. - -type: boolean - -example: true - --- - -*`file.code_signature.valid`*:: -+ --- -Boolean to capture if the digital signature is verified against the binary content. -Leave unpopulated if a certificate was unchecked. - -type: boolean - -example: true - --- - -*`file.created`*:: -+ --- -File creation time. -Note that not all filesystems store the creation time. - -type: date - --- - -*`file.ctime`*:: -+ --- -Last time the file attributes or metadata changed. -Note that changes to the file content will update `mtime`. This implies `ctime` will be adjusted at the same time, since `mtime` is an attribute of the file. - -type: date - --- - -*`file.device`*:: -+ --- -Device that is the source of the file. - -type: keyword - -example: sda - --- - -*`file.directory`*:: -+ --- -Directory where the file is located. It should include the drive letter, when appropriate. - -type: keyword - -example: /home/alice - --- - -*`file.drive_letter`*:: -+ --- -Drive letter where the file is located. This field is only relevant on Windows. -The value should be uppercase, and not include the colon. - -type: keyword - -example: C - --- - -*`file.elf.architecture`*:: -+ --- -Machine architecture of the ELF file. - -type: keyword - -example: x86-64 - --- - -*`file.elf.byte_order`*:: -+ --- -Byte sequence of ELF file. - -type: keyword - -example: Little Endian - --- - -*`file.elf.cpu_type`*:: -+ --- -CPU type of the ELF file. - -type: keyword - -example: Intel - --- - -*`file.elf.creation_date`*:: -+ --- -Extracted when possible from the file's metadata. Indicates when it was built or compiled. It can also be faked by malware creators. - -type: date - --- - -*`file.elf.exports`*:: -+ --- -List of exported element names and types. - -type: flattened - --- - -*`file.elf.header.abi_version`*:: -+ --- -Version of the ELF Application Binary Interface (ABI). - -type: keyword - --- - -*`file.elf.header.class`*:: -+ --- -Header class of the ELF file. - -type: keyword - --- - -*`file.elf.header.data`*:: -+ --- -Data table of the ELF header. - -type: keyword - --- - -*`file.elf.header.entrypoint`*:: -+ --- -Header entrypoint of the ELF file. - -type: long - -format: string - --- - -*`file.elf.header.object_version`*:: -+ --- -"0x1" for original ELF files. - -type: keyword - --- - -*`file.elf.header.os_abi`*:: -+ --- -Application Binary Interface (ABI) of the Linux OS. - -type: keyword - --- - -*`file.elf.header.type`*:: -+ --- -Header type of the ELF file. - -type: keyword - --- - -*`file.elf.header.version`*:: -+ --- -Version of the ELF header. - -type: keyword - --- - -*`file.elf.imports`*:: -+ --- -List of imported element names and types. - -type: flattened - --- - -*`file.elf.sections`*:: -+ --- -An array containing an object for each section of the ELF file. -The keys that should be present in these objects are defined by sub-fields underneath `elf.sections.*`. - -type: nested - --- - -*`file.elf.sections.chi2`*:: -+ --- -Chi-square probability distribution of the section. - -type: long - -format: number - --- - -*`file.elf.sections.entropy`*:: -+ --- -Shannon entropy calculation from the section. - -type: long - -format: number - --- - -*`file.elf.sections.flags`*:: -+ --- -ELF Section List flags. - -type: keyword - --- - -*`file.elf.sections.name`*:: -+ --- -ELF Section List name. - -type: keyword - --- - -*`file.elf.sections.physical_offset`*:: -+ --- -ELF Section List offset. - -type: keyword - --- - -*`file.elf.sections.physical_size`*:: -+ --- -ELF Section List physical size. - -type: long - -format: bytes - --- - -*`file.elf.sections.type`*:: -+ --- -ELF Section List type. - -type: keyword - --- - -*`file.elf.sections.virtual_address`*:: -+ --- -ELF Section List virtual address. - -type: long - -format: string - --- - -*`file.elf.sections.virtual_size`*:: -+ --- -ELF Section List virtual size. - -type: long - -format: string - --- - -*`file.elf.segments`*:: -+ --- -An array containing an object for each segment of the ELF file. -The keys that should be present in these objects are defined by sub-fields underneath `elf.segments.*`. - -type: nested - --- - -*`file.elf.segments.sections`*:: -+ --- -ELF object segment sections. - -type: keyword - --- - -*`file.elf.segments.type`*:: -+ --- -ELF object segment type. - -type: keyword - --- - -*`file.elf.shared_libraries`*:: -+ --- -List of shared libraries used by this ELF object. - -type: keyword - --- - -*`file.elf.telfhash`*:: -+ --- -telfhash symbol hash for ELF file. - -type: keyword - --- - -*`file.extension`*:: -+ --- -File extension, excluding the leading dot. -Note that when the file name has multiple extensions (example.tar.gz), only the last one should be captured ("gz", not "tar.gz"). - -type: keyword - -example: png - --- - -*`file.fork_name`*:: -+ --- -A fork is additional data associated with a filesystem object. -On Linux, a resource fork is used to store additional data with a filesystem object. A file always has at least one fork for the data portion, and additional forks may exist. -On NTFS, this is analogous to an Alternate Data Stream (ADS), and the default data stream for a file is just called $DATA. Zone.Identifier is commonly used by Windows to track contents downloaded from the Internet. An ADS is typically of the form: `C:\path\to\filename.extension:some_fork_name`, and `some_fork_name` is the value that should populate `fork_name`. `filename.extension` should populate `file.name`, and `extension` should populate `file.extension`. The full path, `file.path`, will include the fork name. - -type: keyword - -example: Zone.Identifer - --- - -*`file.gid`*:: -+ --- -Primary group ID (GID) of the file. - -type: keyword - -example: 1001 - --- - -*`file.group`*:: -+ --- -Primary group name of the file. - -type: keyword - -example: alice - --- - -*`file.hash.md5`*:: -+ --- -MD5 hash. - -type: keyword - --- - -*`file.hash.sha1`*:: -+ --- -SHA1 hash. - -type: keyword - --- - -*`file.hash.sha256`*:: -+ --- -SHA256 hash. - -type: keyword - --- - -*`file.hash.sha512`*:: -+ --- -SHA512 hash. - -type: keyword - --- - -*`file.hash.ssdeep`*:: -+ --- -SSDEEP hash. - -type: keyword - --- - -*`file.inode`*:: -+ --- -Inode representing the file in the filesystem. - -type: keyword - -example: 256383 - --- - -*`file.mime_type`*:: -+ --- -MIME type should identify the format of the file or stream of bytes using https://www.iana.org/assignments/media-types/media-types.xhtml[IANA official types], where possible. When more than one type is applicable, the most specific type should be used. - -type: keyword - --- - -*`file.mode`*:: -+ --- -Mode of the file in octal representation. - -type: keyword - -example: 0640 - --- - -*`file.mtime`*:: -+ --- -Last time the file content was modified. - -type: date - --- - -*`file.name`*:: -+ --- -Name of the file including the extension, without the directory. - -type: keyword - -example: example.png - --- - -*`file.owner`*:: -+ --- -File owner's username. - -type: keyword - -example: alice - --- - -*`file.path`*:: -+ --- -Full path to the file, including the file name. It should include the drive letter, when appropriate. - -type: keyword - -example: /home/alice/example.png - --- - -*`file.path.text`*:: -+ --- -type: match_only_text - --- - -*`file.pe.architecture`*:: -+ --- -CPU architecture target for the file. - -type: keyword - -example: x64 - --- - -*`file.pe.company`*:: -+ --- -Internal company name of the file, provided at compile-time. - -type: keyword - -example: Microsoft Corporation - --- - -*`file.pe.description`*:: -+ --- -Internal description of the file, provided at compile-time. - -type: keyword - -example: Paint - --- - -*`file.pe.file_version`*:: -+ --- -Internal version of the file, provided at compile-time. - -type: keyword - -example: 6.3.9600.17415 - --- - -*`file.pe.imphash`*:: -+ --- -A hash of the imports in a PE file. An imphash -- or import hash -- can be used to fingerprint binaries even after recompilation or other code-level transformations have occurred, which would change more traditional hash values. -Learn more at https://www.fireeye.com/blog/threat-research/2014/01/tracking-malware-import-hashing.html. - -type: keyword - -example: 0c6803c4e922103c4dca5963aad36ddf - --- - -*`file.pe.original_file_name`*:: -+ --- -Internal name of the file, provided at compile-time. - -type: keyword - -example: MSPAINT.EXE - --- - -*`file.pe.product`*:: -+ --- -Internal product name of the file, provided at compile-time. - -type: keyword - -example: Microsoft® Windows® Operating System - --- - -*`file.size`*:: -+ --- -File size in bytes. -Only relevant when `file.type` is "file". - -type: long - -example: 16384 - --- - -*`file.target_path`*:: -+ --- -Target path for symlinks. - -type: keyword - --- - -*`file.target_path.text`*:: -+ --- -type: match_only_text - --- - -*`file.type`*:: -+ --- -File type (file, dir, or symlink). - -type: keyword - -example: file - --- - -*`file.uid`*:: -+ --- -The user ID (UID) or security identifier (SID) of the file owner. - -type: keyword - -example: 1001 - --- - -*`file.x509.alternative_names`*:: -+ --- -List of subject alternative names (SAN). Name types vary by certificate authority and certificate type but commonly contain IP addresses, DNS names (and wildcards), and email addresses. - -type: keyword - -example: *.elastic.co - --- - -*`file.x509.issuer.common_name`*:: -+ --- -List of common name (CN) of issuing certificate authority. - -type: keyword - -example: Example SHA2 High Assurance Server CA - --- - -*`file.x509.issuer.country`*:: -+ --- -List of country (C) codes - -type: keyword - -example: US - --- - -*`file.x509.issuer.distinguished_name`*:: -+ --- -Distinguished name (DN) of issuing certificate authority. - -type: keyword - -example: C=US, O=Example Inc, OU=www.example.com, CN=Example SHA2 High Assurance Server CA - --- - -*`file.x509.issuer.locality`*:: -+ --- -List of locality names (L) - -type: keyword - -example: Mountain View - --- - -*`file.x509.issuer.organization`*:: -+ --- -List of organizations (O) of issuing certificate authority. - -type: keyword - -example: Example Inc - --- - -*`file.x509.issuer.organizational_unit`*:: -+ --- -List of organizational units (OU) of issuing certificate authority. - -type: keyword - -example: www.example.com - --- - -*`file.x509.issuer.state_or_province`*:: -+ --- -List of state or province names (ST, S, or P) - -type: keyword - -example: California - --- - -*`file.x509.not_after`*:: -+ --- -Time at which the certificate is no longer considered valid. - -type: date - -example: 2020-07-16 03:15:39+00:00 - --- - -*`file.x509.not_before`*:: -+ --- -Time at which the certificate is first considered valid. - -type: date - -example: 2019-08-16 01:40:25+00:00 - --- - -*`file.x509.public_key_algorithm`*:: -+ --- -Algorithm used to generate the public key. - -type: keyword - -example: RSA - --- - -*`file.x509.public_key_curve`*:: -+ --- -The curve used by the elliptic curve public key algorithm. This is algorithm specific. - -type: keyword - -example: nistp521 - --- - -*`file.x509.public_key_exponent`*:: -+ --- -Exponent used to derive the public key. This is algorithm specific. - -type: long - -example: 65537 - -Field is not indexed. - --- - -*`file.x509.public_key_size`*:: -+ --- -The size of the public key space in bits. - -type: long - -example: 2048 - --- - -*`file.x509.serial_number`*:: -+ --- -Unique serial number issued by the certificate authority. For consistency, if this value is alphanumeric, it should be formatted without colons and uppercase characters. - -type: keyword - -example: 55FBB9C7DEBF09809D12CCAA - --- - -*`file.x509.signature_algorithm`*:: -+ --- -Identifier for certificate signature algorithm. We recommend using names found in Go Lang Crypto library. See https://github.com/golang/go/blob/go1.14/src/crypto/x509/x509.go#L337-L353. - -type: keyword - -example: SHA256-RSA - --- - -*`file.x509.subject.common_name`*:: -+ --- -List of common names (CN) of subject. - -type: keyword - -example: shared.global.example.net - --- - -*`file.x509.subject.country`*:: -+ --- -List of country (C) code - -type: keyword - -example: US - --- - -*`file.x509.subject.distinguished_name`*:: -+ --- -Distinguished name (DN) of the certificate subject entity. - -type: keyword - -example: C=US, ST=California, L=San Francisco, O=Example, Inc., CN=shared.global.example.net - --- - -*`file.x509.subject.locality`*:: -+ --- -List of locality names (L) - -type: keyword - -example: San Francisco - --- - -*`file.x509.subject.organization`*:: -+ --- -List of organizations (O) of subject. - -type: keyword - -example: Example, Inc. - --- - -*`file.x509.subject.organizational_unit`*:: -+ --- -List of organizational units (OU) of subject. - -type: keyword - --- - -*`file.x509.subject.state_or_province`*:: -+ --- -List of state or province names (ST, S, or P) - -type: keyword - -example: California - --- - -*`file.x509.version_number`*:: -+ --- -Version of x509 format. - -type: keyword - -example: 3 - --- - -[float] -=== geo - -Geo fields can carry data about a specific location related to an event. -This geolocation information can be derived from techniques such as Geo IP, or be user-supplied. - - -*`geo.city_name`*:: -+ --- -City name. - -type: keyword - -example: Montreal - --- - -*`geo.continent_code`*:: -+ --- -Two-letter code representing continent's name. - -type: keyword - -example: NA - --- - -*`geo.continent_name`*:: -+ --- -Name of the continent. - -type: keyword - -example: North America - --- - -*`geo.country_iso_code`*:: -+ --- -Country ISO code. - -type: keyword - -example: CA - --- - -*`geo.country_name`*:: -+ --- -Country name. - -type: keyword - -example: Canada - --- - -*`geo.location`*:: -+ --- -Longitude and latitude. - -type: geo_point - -example: { "lon": -73.614830, "lat": 45.505918 } - --- - -*`geo.name`*:: -+ --- -User-defined description of a location, at the level of granularity they care about. -Could be the name of their data centers, the floor number, if this describes a local physical entity, city names. -Not typically used in automated geolocation. - -type: keyword - -example: boston-dc - --- - -*`geo.postal_code`*:: -+ --- -Postal code associated with the location. -Values appropriate for this field may also be known as a postcode or ZIP code and will vary widely from country to country. - -type: keyword - -example: 94040 - --- - -*`geo.region_iso_code`*:: -+ --- -Region ISO code. - -type: keyword - -example: CA-QC - --- - -*`geo.region_name`*:: -+ --- -Region name. - -type: keyword - -example: Quebec - --- - -*`geo.timezone`*:: -+ --- -The time zone of the location, such as IANA time zone name. - -type: keyword - -example: America/Argentina/Buenos_Aires - --- - -[float] -=== group - -The group fields are meant to represent groups that are relevant to the event. - - -*`group.domain`*:: -+ --- -Name of the directory the group is a member of. -For example, an LDAP or Active Directory domain name. - -type: keyword - --- - -*`group.id`*:: -+ --- -Unique identifier for the group on the system/platform. - -type: keyword - --- - -*`group.name`*:: -+ --- -Name of the group. - -type: keyword - --- - -[float] -=== hash - -The hash fields represent different bitwise hash algorithms and their values. -Field names for common hashes (e.g. MD5, SHA1) are predefined. Add fields for other hashes by lowercasing the hash algorithm name and using underscore separators as appropriate (snake case, e.g. sha3_512). -Note that this fieldset is used for common hashes that may be computed over a range of generic bytes. Entity-specific hashes such as ja3 or imphash are placed in the fieldsets to which they relate (tls and pe, respectively). - - -*`hash.md5`*:: -+ --- -MD5 hash. - -type: keyword - --- - -*`hash.sha1`*:: -+ --- -SHA1 hash. - -type: keyword - --- - -*`hash.sha256`*:: -+ --- -SHA256 hash. - -type: keyword - --- - -*`hash.sha512`*:: -+ --- -SHA512 hash. - -type: keyword - --- - -*`hash.ssdeep`*:: -+ --- -SSDEEP hash. - -type: keyword - --- - -[float] -=== host - -A host is defined as a general computing instance. -ECS host.* fields should be populated with details about the host on which the event happened, or from which the measurement was taken. Host types include hardware, virtual machines, Docker containers, and Kubernetes nodes. - - -*`host.architecture`*:: -+ --- -Operating system architecture. - -type: keyword - -example: x86_64 - --- - -*`host.cpu.usage`*:: -+ --- -Percent CPU used which is normalized by the number of CPU cores and it ranges from 0 to 1. -Scaling factor: 1000. -For example: For a two core host, this value should be the average of the two cores, between 0 and 1. - -type: scaled_float - --- - -*`host.disk.read.bytes`*:: -+ --- -The total number of bytes (gauge) read successfully (aggregated from all disks) since the last metric collection. - -type: long - --- - -*`host.disk.write.bytes`*:: -+ --- -The total number of bytes (gauge) written successfully (aggregated from all disks) since the last metric collection. - -type: long - --- - -*`host.domain`*:: -+ --- -Name of the domain of which the host is a member. -For example, on Windows this could be the host's Active Directory domain or NetBIOS domain name. For Linux this could be the domain of the host's LDAP provider. - -type: keyword - -example: CONTOSO - --- - -*`host.geo.city_name`*:: -+ --- -City name. - -type: keyword - -example: Montreal - --- - -*`host.geo.continent_code`*:: -+ --- -Two-letter code representing continent's name. - -type: keyword - -example: NA - --- - -*`host.geo.continent_name`*:: -+ --- -Name of the continent. - -type: keyword - -example: North America - --- - -*`host.geo.country_iso_code`*:: -+ --- -Country ISO code. - -type: keyword - -example: CA - --- - -*`host.geo.country_name`*:: -+ --- -Country name. - -type: keyword - -example: Canada - --- - -*`host.geo.location`*:: -+ --- -Longitude and latitude. - -type: geo_point - -example: { "lon": -73.614830, "lat": 45.505918 } - --- - -*`host.geo.name`*:: -+ --- -User-defined description of a location, at the level of granularity they care about. -Could be the name of their data centers, the floor number, if this describes a local physical entity, city names. -Not typically used in automated geolocation. - -type: keyword - -example: boston-dc - --- - -*`host.geo.postal_code`*:: -+ --- -Postal code associated with the location. -Values appropriate for this field may also be known as a postcode or ZIP code and will vary widely from country to country. - -type: keyword - -example: 94040 - --- - -*`host.geo.region_iso_code`*:: -+ --- -Region ISO code. - -type: keyword - -example: CA-QC - --- - -*`host.geo.region_name`*:: -+ --- -Region name. - -type: keyword - -example: Quebec - --- - -*`host.geo.timezone`*:: -+ --- -The time zone of the location, such as IANA time zone name. - -type: keyword - -example: America/Argentina/Buenos_Aires - --- - -*`host.hostname`*:: -+ --- -Hostname of the host. -It normally contains what the `hostname` command returns on the host machine. - -type: keyword - --- - -*`host.id`*:: -+ --- -Unique host id. -As hostname is not always unique, use values that are meaningful in your environment. -Example: The current usage of `beat.name`. - -type: keyword - --- - -*`host.ip`*:: -+ --- -Host ip addresses. - -type: ip - --- - -*`host.mac`*:: -+ --- -Host MAC addresses. -The notation format from RFC 7042 is suggested: Each octet (that is, 8-bit byte) is represented by two [uppercase] hexadecimal digits giving the value of the octet as an unsigned integer. Successive octets are separated by a hyphen. - -type: keyword - -example: ["00-00-5E-00-53-23", "00-00-5E-00-53-24"] - --- - -*`host.name`*:: -+ --- -Name of the host. -It can contain what `hostname` returns on Unix systems, the fully qualified domain name, or a name specified by the user. The sender decides which value to use. - -type: keyword - --- - -*`host.network.egress.bytes`*:: -+ --- -The number of bytes (gauge) sent out on all network interfaces by the host since the last metric collection. - -type: long - --- - -*`host.network.egress.packets`*:: -+ --- -The number of packets (gauge) sent out on all network interfaces by the host since the last metric collection. - -type: long - --- - -*`host.network.ingress.bytes`*:: -+ --- -The number of bytes received (gauge) on all network interfaces by the host since the last metric collection. - -type: long - --- - -*`host.network.ingress.packets`*:: -+ --- -The number of packets (gauge) received on all network interfaces by the host since the last metric collection. - -type: long - --- - -*`host.os.family`*:: -+ --- -OS family (such as redhat, debian, freebsd, windows). - -type: keyword - -example: debian - --- - -*`host.os.full`*:: -+ --- -Operating system name, including the version or code name. - -type: keyword - -example: Mac OS Mojave - --- - -*`host.os.full.text`*:: -+ --- -type: match_only_text - --- - -*`host.os.kernel`*:: -+ --- -Operating system kernel version as a raw string. - -type: keyword - -example: 4.4.0-112-generic - --- - -*`host.os.name`*:: -+ --- -Operating system name, without the version. - -type: keyword - -example: Mac OS X - --- - -*`host.os.name.text`*:: -+ --- -type: match_only_text - --- - -*`host.os.platform`*:: -+ --- -Operating system platform (such centos, ubuntu, windows). - -type: keyword - -example: darwin - --- - -*`host.os.type`*:: -+ --- -Use the `os.type` field to categorize the operating system into one of the broad commercial families. -One of these following values should be used (lowercase): linux, macos, unix, windows. -If the OS you're dealing with is not in the list, the field should not be populated. Please let us know by opening an issue with ECS, to propose its addition. - -type: keyword - -example: macos - --- - -*`host.os.version`*:: -+ --- -Operating system version as a raw string. - -type: keyword - -example: 10.14.1 - --- - -*`host.type`*:: -+ --- -Type of host. -For Cloud providers this can be the machine type like `t2.medium`. If vm, this could be the container, for example, or other information meaningful in your environment. - -type: keyword - --- - -*`host.uptime`*:: -+ --- -Seconds the host has been up. - -type: long - -example: 1325 - --- - -[float] -=== http - -Fields related to HTTP activity. Use the `url` field set to store the url of the request. - - -*`http.request.body.bytes`*:: -+ --- -Size in bytes of the request body. - -type: long - -example: 887 - -format: bytes - --- - -*`http.request.body.content`*:: -+ --- -The full HTTP request body. - -type: wildcard - -example: Hello world - --- - -*`http.request.body.content.text`*:: -+ --- -type: match_only_text - --- - -*`http.request.bytes`*:: -+ --- -Total size in bytes of the request (body and headers). - -type: long - -example: 1437 - -format: bytes - --- - -*`http.request.id`*:: -+ --- -A unique identifier for each HTTP request to correlate logs between clients and servers in transactions. -The id may be contained in a non-standard HTTP header, such as `X-Request-ID` or `X-Correlation-ID`. - -type: keyword - -example: 123e4567-e89b-12d3-a456-426614174000 - --- - -*`http.request.method`*:: -+ --- -HTTP request method. -The value should retain its casing from the original event. For example, `GET`, `get`, and `GeT` are all considered valid values for this field. - -type: keyword - -example: POST - --- - -*`http.request.mime_type`*:: -+ --- -Mime type of the body of the request. -This value must only be populated based on the content of the request body, not on the `Content-Type` header. Comparing the mime type of a request with the request's Content-Type header can be helpful in detecting threats or misconfigured clients. - -type: keyword - -example: image/gif - --- - -*`http.request.referrer`*:: -+ --- -Referrer for this HTTP request. - -type: keyword - -example: https://blog.example.com/ - --- - -*`http.response.body.bytes`*:: -+ --- -Size in bytes of the response body. - -type: long - -example: 887 - -format: bytes - --- - -*`http.response.body.content`*:: -+ --- -The full HTTP response body. - -type: wildcard - -example: Hello world - --- - -*`http.response.body.content.text`*:: -+ --- -type: match_only_text - --- - -*`http.response.bytes`*:: -+ --- -Total size in bytes of the response (body and headers). - -type: long - -example: 1437 - -format: bytes - --- - -*`http.response.mime_type`*:: -+ --- -Mime type of the body of the response. -This value must only be populated based on the content of the response body, not on the `Content-Type` header. Comparing the mime type of a response with the response's Content-Type header can be helpful in detecting misconfigured servers. - -type: keyword - -example: image/gif - --- - -*`http.response.status_code`*:: -+ --- -HTTP response status code. - -type: long - -example: 404 - -format: string - --- - -*`http.version`*:: -+ --- -HTTP version. - -type: keyword - -example: 1.1 - --- - -[float] -=== interface - -The interface fields are used to record ingress and egress interface information when reported by an observer (e.g. firewall, router, load balancer) in the context of the observer handling a network connection. In the case of a single observer interface (e.g. network sensor on a span port) only the observer.ingress information should be populated. - - -*`interface.alias`*:: -+ --- -Interface alias as reported by the system, typically used in firewall implementations for e.g. inside, outside, or dmz logical interface naming. - -type: keyword - -example: outside - --- - -*`interface.id`*:: -+ --- -Interface ID as reported by an observer (typically SNMP interface ID). - -type: keyword - -example: 10 - --- - -*`interface.name`*:: -+ --- -Interface name as reported by the system. - -type: keyword - -example: eth0 - --- - -[float] -=== log - -Details about the event's logging mechanism or logging transport. -The log.* fields are typically populated with details about the logging mechanism used to create and/or transport the event. For example, syslog details belong under `log.syslog.*`. -The details specific to your event source are typically not logged under `log.*`, but rather in `event.*` or in other ECS fields. - - -*`log.file.path`*:: -+ --- -Full path to the log file this event came from, including the file name. It should include the drive letter, when appropriate. -If the event wasn't read from a log file, do not populate this field. - -type: keyword - -example: /var/log/fun-times.log - --- - -*`log.level`*:: -+ --- -Original log level of the log event. -If the source of the event provides a log level or textual severity, this is the one that goes in `log.level`. If your source doesn't specify one, you may put your event transport's severity here (e.g. Syslog severity). -Some examples are `warn`, `err`, `i`, `informational`. - -type: keyword - -example: error - --- - -*`log.logger`*:: -+ --- -The name of the logger inside an application. This is usually the name of the class which initialized the logger, or can be a custom name. - -type: keyword - -example: org.elasticsearch.bootstrap.Bootstrap - --- - -*`log.origin.file.line`*:: -+ --- -The line number of the file containing the source code which originated the log event. - -type: long - -example: 42 - --- - -*`log.origin.file.name`*:: -+ --- -The name of the file containing the source code which originated the log event. -Note that this field is not meant to capture the log file. The correct field to capture the log file is `log.file.path`. - -type: keyword - -example: Bootstrap.java - --- - -*`log.origin.function`*:: -+ --- -The name of the function or method which originated the log event. - -type: keyword - -example: init - --- - -*`log.syslog`*:: -+ --- -The Syslog metadata of the event, if the event was transmitted via Syslog. Please see RFCs 5424 or 3164. - -type: object - --- - -*`log.syslog.facility.code`*:: -+ --- -The Syslog numeric facility of the log event, if available. -According to RFCs 5424 and 3164, this value should be an integer between 0 and 23. - -type: long - -example: 23 - -format: string - --- - -*`log.syslog.facility.name`*:: -+ --- -The Syslog text-based facility of the log event, if available. - -type: keyword - -example: local7 - --- - -*`log.syslog.priority`*:: -+ --- -Syslog numeric priority of the event, if available. -According to RFCs 5424 and 3164, the priority is 8 * facility + severity. This number is therefore expected to contain a value between 0 and 191. - -type: long - -example: 135 - -format: string - --- - -*`log.syslog.severity.code`*:: -+ --- -The Syslog numeric severity of the log event, if available. -If the event source publishing via Syslog provides a different numeric severity value (e.g. firewall, IDS), your source's numeric severity should go to `event.severity`. If the event source does not specify a distinct severity, you can optionally copy the Syslog severity to `event.severity`. - -type: long - -example: 3 - --- - -*`log.syslog.severity.name`*:: -+ --- -The Syslog numeric severity of the log event, if available. -If the event source publishing via Syslog provides a different severity value (e.g. firewall, IDS), your source's text severity should go to `log.level`. If the event source does not specify a distinct severity, you can optionally copy the Syslog severity to `log.level`. - -type: keyword - -example: Error - --- - -[float] -=== network - -The network is defined as the communication path over which a host or network event happens. -The network.* fields should be populated with details about the network activity associated with an event. - - -*`network.application`*:: -+ --- -When a specific application or service is identified from network connection details (source/dest IPs, ports, certificates, or wire format), this field captures the application's or service's name. -For example, the original event identifies the network connection being from a specific web service in a `https` network connection, like `facebook` or `twitter`. -The field value must be normalized to lowercase for querying. - -type: keyword - -example: aim - --- - -*`network.bytes`*:: -+ --- -Total bytes transferred in both directions. -If `source.bytes` and `destination.bytes` are known, `network.bytes` is their sum. - -type: long - -example: 368 - -format: bytes - --- - -*`network.community_id`*:: -+ --- -A hash of source and destination IPs and ports, as well as the protocol used in a communication. This is a tool-agnostic standard to identify flows. -Learn more at https://github.com/corelight/community-id-spec. - -type: keyword - -example: 1:hO+sN4H+MG5MY/8hIrXPqc4ZQz0= - --- - -*`network.direction`*:: -+ --- -Direction of the network traffic. -Recommended values are: - * ingress - * egress - * inbound - * outbound - * internal - * external - * unknown - -When mapping events from a host-based monitoring context, populate this field from the host's point of view, using the values "ingress" or "egress". -When mapping events from a network or perimeter-based monitoring context, populate this field from the point of view of the network perimeter, using the values "inbound", "outbound", "internal" or "external". -Note that "internal" is not crossing perimeter boundaries, and is meant to describe communication between two hosts within the perimeter. Note also that "external" is meant to describe traffic between two hosts that are external to the perimeter. This could for example be useful for ISPs or VPN service providers. - -type: keyword - -example: inbound - --- - -*`network.forwarded_ip`*:: -+ --- -Host IP address when the source IP address is the proxy. - -type: ip - -example: 192.1.1.2 - --- - -*`network.iana_number`*:: -+ --- -IANA Protocol Number (https://www.iana.org/assignments/protocol-numbers/protocol-numbers.xhtml). Standardized list of protocols. This aligns well with NetFlow and sFlow related logs which use the IANA Protocol Number. - -type: keyword - -example: 6 - --- - -*`network.inner`*:: -+ --- -Network.inner fields are added in addition to network.vlan fields to describe the innermost VLAN when q-in-q VLAN tagging is present. Allowed fields include vlan.id and vlan.name. Inner vlan fields are typically used when sending traffic with multiple 802.1q encapsulations to a network sensor (e.g. Zeek, Wireshark.) - -type: object - --- - -*`network.inner.vlan.id`*:: -+ --- -VLAN ID as reported by the observer. - -type: keyword - -example: 10 - --- - -*`network.inner.vlan.name`*:: -+ --- -Optional VLAN name as reported by the observer. - -type: keyword - -example: outside - --- - -*`network.name`*:: -+ --- -Name given by operators to sections of their network. - -type: keyword - -example: Guest Wifi - --- - -*`network.packets`*:: -+ --- -Total packets transferred in both directions. -If `source.packets` and `destination.packets` are known, `network.packets` is their sum. - -type: long - -example: 24 - --- - -*`network.protocol`*:: -+ --- -In the OSI Model this would be the Application Layer protocol. For example, `http`, `dns`, or `ssh`. -The field value must be normalized to lowercase for querying. - -type: keyword - -example: http - --- - -*`network.transport`*:: -+ --- -Same as network.iana_number, but instead using the Keyword name of the transport layer (udp, tcp, ipv6-icmp, etc.) -The field value must be normalized to lowercase for querying. - -type: keyword - -example: tcp - --- - -*`network.type`*:: -+ --- -In the OSI Model this would be the Network Layer. ipv4, ipv6, ipsec, pim, etc -The field value must be normalized to lowercase for querying. - -type: keyword - -example: ipv4 - --- - -*`network.vlan.id`*:: -+ --- -VLAN ID as reported by the observer. - -type: keyword - -example: 10 - --- - -*`network.vlan.name`*:: -+ --- -Optional VLAN name as reported by the observer. - -type: keyword - -example: outside - --- - -[float] -=== observer - -An observer is defined as a special network, security, or application device used to detect, observe, or create network, security, or application-related events and metrics. -This could be a custom hardware appliance or a server that has been configured to run special network, security, or application software. Examples include firewalls, web proxies, intrusion detection/prevention systems, network monitoring sensors, web application firewalls, data loss prevention systems, and APM servers. The observer.* fields shall be populated with details of the system, if any, that detects, observes and/or creates a network, security, or application event or metric. Message queues and ETL components used in processing events or metrics are not considered observers in ECS. - - -*`observer.egress`*:: -+ --- -Observer.egress holds information like interface number and name, vlan, and zone information to classify egress traffic. Single armed monitoring such as a network sensor on a span port should only use observer.ingress to categorize traffic. - -type: object - --- - -*`observer.egress.interface.alias`*:: -+ --- -Interface alias as reported by the system, typically used in firewall implementations for e.g. inside, outside, or dmz logical interface naming. - -type: keyword - -example: outside - --- - -*`observer.egress.interface.id`*:: -+ --- -Interface ID as reported by an observer (typically SNMP interface ID). - -type: keyword - -example: 10 - --- - -*`observer.egress.interface.name`*:: -+ --- -Interface name as reported by the system. - -type: keyword - -example: eth0 - --- - -*`observer.egress.vlan.id`*:: -+ --- -VLAN ID as reported by the observer. - -type: keyword - -example: 10 - --- - -*`observer.egress.vlan.name`*:: -+ --- -Optional VLAN name as reported by the observer. - -type: keyword - -example: outside - --- - -*`observer.egress.zone`*:: -+ --- -Network zone of outbound traffic as reported by the observer to categorize the destination area of egress traffic, e.g. Internal, External, DMZ, HR, Legal, etc. - -type: keyword - -example: Public_Internet - --- - -*`observer.geo.city_name`*:: -+ --- -City name. - -type: keyword - -example: Montreal - --- - -*`observer.geo.continent_code`*:: -+ --- -Two-letter code representing continent's name. - -type: keyword - -example: NA - --- - -*`observer.geo.continent_name`*:: -+ --- -Name of the continent. - -type: keyword - -example: North America - --- - -*`observer.geo.country_iso_code`*:: -+ --- -Country ISO code. - -type: keyword - -example: CA - --- - -*`observer.geo.country_name`*:: -+ --- -Country name. - -type: keyword - -example: Canada - --- - -*`observer.geo.location`*:: -+ --- -Longitude and latitude. - -type: geo_point - -example: { "lon": -73.614830, "lat": 45.505918 } - --- - -*`observer.geo.name`*:: -+ --- -User-defined description of a location, at the level of granularity they care about. -Could be the name of their data centers, the floor number, if this describes a local physical entity, city names. -Not typically used in automated geolocation. - -type: keyword - -example: boston-dc - --- - -*`observer.geo.postal_code`*:: -+ --- -Postal code associated with the location. -Values appropriate for this field may also be known as a postcode or ZIP code and will vary widely from country to country. - -type: keyword - -example: 94040 - --- - -*`observer.geo.region_iso_code`*:: -+ --- -Region ISO code. - -type: keyword - -example: CA-QC - --- - -*`observer.geo.region_name`*:: -+ --- -Region name. - -type: keyword - -example: Quebec - --- - -*`observer.geo.timezone`*:: -+ --- -The time zone of the location, such as IANA time zone name. - -type: keyword - -example: America/Argentina/Buenos_Aires - --- - -*`observer.hostname`*:: -+ --- -Hostname of the observer. - -type: keyword - --- - -*`observer.ingress`*:: -+ --- -Observer.ingress holds information like interface number and name, vlan, and zone information to classify ingress traffic. Single armed monitoring such as a network sensor on a span port should only use observer.ingress to categorize traffic. - -type: object - --- - -*`observer.ingress.interface.alias`*:: -+ --- -Interface alias as reported by the system, typically used in firewall implementations for e.g. inside, outside, or dmz logical interface naming. - -type: keyword - -example: outside - --- - -*`observer.ingress.interface.id`*:: -+ --- -Interface ID as reported by an observer (typically SNMP interface ID). - -type: keyword - -example: 10 - --- - -*`observer.ingress.interface.name`*:: -+ --- -Interface name as reported by the system. - -type: keyword - -example: eth0 - --- - -*`observer.ingress.vlan.id`*:: -+ --- -VLAN ID as reported by the observer. - -type: keyword - -example: 10 - --- - -*`observer.ingress.vlan.name`*:: -+ --- -Optional VLAN name as reported by the observer. - -type: keyword - -example: outside - --- - -*`observer.ingress.zone`*:: -+ --- -Network zone of incoming traffic as reported by the observer to categorize the source area of ingress traffic. e.g. internal, External, DMZ, HR, Legal, etc. - -type: keyword - -example: DMZ - --- - -*`observer.ip`*:: -+ --- -IP addresses of the observer. - -type: ip - --- - -*`observer.mac`*:: -+ --- -MAC addresses of the observer. -The notation format from RFC 7042 is suggested: Each octet (that is, 8-bit byte) is represented by two [uppercase] hexadecimal digits giving the value of the octet as an unsigned integer. Successive octets are separated by a hyphen. - -type: keyword - -example: ["00-00-5E-00-53-23", "00-00-5E-00-53-24"] - --- - -*`observer.name`*:: -+ --- -Custom name of the observer. -This is a name that can be given to an observer. This can be helpful for example if multiple firewalls of the same model are used in an organization. -If no custom name is needed, the field can be left empty. - -type: keyword - -example: 1_proxySG - --- - -*`observer.os.family`*:: -+ --- -OS family (such as redhat, debian, freebsd, windows). - -type: keyword - -example: debian - --- - -*`observer.os.full`*:: -+ --- -Operating system name, including the version or code name. - -type: keyword - -example: Mac OS Mojave - --- - -*`observer.os.full.text`*:: -+ --- -type: match_only_text - --- - -*`observer.os.kernel`*:: -+ --- -Operating system kernel version as a raw string. - -type: keyword - -example: 4.4.0-112-generic - --- - -*`observer.os.name`*:: -+ --- -Operating system name, without the version. - -type: keyword - -example: Mac OS X - --- - -*`observer.os.name.text`*:: -+ --- -type: match_only_text - --- - -*`observer.os.platform`*:: -+ --- -Operating system platform (such centos, ubuntu, windows). - -type: keyword - -example: darwin - --- - -*`observer.os.type`*:: -+ --- -Use the `os.type` field to categorize the operating system into one of the broad commercial families. -One of these following values should be used (lowercase): linux, macos, unix, windows. -If the OS you're dealing with is not in the list, the field should not be populated. Please let us know by opening an issue with ECS, to propose its addition. - -type: keyword - -example: macos - --- - -*`observer.os.version`*:: -+ --- -Operating system version as a raw string. - -type: keyword - -example: 10.14.1 - --- - -*`observer.product`*:: -+ --- -The product name of the observer. - -type: keyword - -example: s200 - --- - -*`observer.serial_number`*:: -+ --- -Observer serial number. - -type: keyword - --- - -*`observer.type`*:: -+ --- -The type of the observer the data is coming from. -There is no predefined list of observer types. Some examples are `forwarder`, `firewall`, `ids`, `ips`, `proxy`, `poller`, `sensor`, `APM server`. - -type: keyword - -example: firewall - --- - -*`observer.vendor`*:: -+ --- -Vendor name of the observer. - -type: keyword - -example: Symantec - --- - -*`observer.version`*:: -+ --- -Observer version. - -type: keyword - --- - -[float] -=== orchestrator - -Fields that describe the resources which container orchestrators manage or act upon. - - -*`orchestrator.api_version`*:: -+ --- -API version being used to carry out the action - -type: keyword - -example: v1beta1 - --- - -*`orchestrator.cluster.name`*:: -+ --- -Name of the cluster. - -type: keyword - --- - -*`orchestrator.cluster.url`*:: -+ --- -URL of the API used to manage the cluster. - -type: keyword - --- - -*`orchestrator.cluster.version`*:: -+ --- -The version of the cluster. - -type: keyword - --- - -*`orchestrator.namespace`*:: -+ --- -Namespace in which the action is taking place. - -type: keyword - -example: kube-system - --- - -*`orchestrator.organization`*:: -+ --- -Organization affected by the event (for multi-tenant orchestrator setups). - -type: keyword - -example: elastic - --- - -*`orchestrator.resource.name`*:: -+ --- -Name of the resource being acted upon. - -type: keyword - -example: test-pod-cdcws - --- - -*`orchestrator.resource.type`*:: -+ --- -Type of resource being acted upon. - -type: keyword - -example: service - --- - -*`orchestrator.type`*:: -+ --- -Orchestrator cluster type (e.g. kubernetes, nomad or cloudfoundry). - -type: keyword - -example: kubernetes - --- - -[float] -=== organization - -The organization fields enrich data with information about the company or entity the data is associated with. -These fields help you arrange or filter data stored in an index by one or multiple organizations. - - -*`organization.id`*:: -+ --- -Unique identifier for the organization. - -type: keyword - --- - -*`organization.name`*:: -+ --- -Organization name. - -type: keyword - --- - -*`organization.name.text`*:: -+ --- -type: match_only_text - --- - -[float] -=== os - -The OS fields contain information about the operating system. - - -*`os.family`*:: -+ --- -OS family (such as redhat, debian, freebsd, windows). - -type: keyword - -example: debian - --- - -*`os.full`*:: -+ --- -Operating system name, including the version or code name. - -type: keyword - -example: Mac OS Mojave - --- - -*`os.full.text`*:: -+ --- -type: match_only_text - --- - -*`os.kernel`*:: -+ --- -Operating system kernel version as a raw string. - -type: keyword - -example: 4.4.0-112-generic - --- - -*`os.name`*:: -+ --- -Operating system name, without the version. - -type: keyword - -example: Mac OS X - --- - -*`os.name.text`*:: -+ --- -type: match_only_text - --- - -*`os.platform`*:: -+ --- -Operating system platform (such centos, ubuntu, windows). - -type: keyword - -example: darwin - --- - -*`os.type`*:: -+ --- -Use the `os.type` field to categorize the operating system into one of the broad commercial families. -One of these following values should be used (lowercase): linux, macos, unix, windows. -If the OS you're dealing with is not in the list, the field should not be populated. Please let us know by opening an issue with ECS, to propose its addition. - -type: keyword - -example: macos - --- - -*`os.version`*:: -+ --- -Operating system version as a raw string. - -type: keyword - -example: 10.14.1 - --- - -[float] -=== package - -These fields contain information about an installed software package. It contains general information about a package, such as name, version or size. It also contains installation details, such as time or location. - - -*`package.architecture`*:: -+ --- -Package architecture. - -type: keyword - -example: x86_64 - --- - -*`package.build_version`*:: -+ --- -Additional information about the build version of the installed package. -For example use the commit SHA of a non-released package. - -type: keyword - -example: 36f4f7e89dd61b0988b12ee000b98966867710cd - --- - -*`package.checksum`*:: -+ --- -Checksum of the installed package for verification. - -type: keyword - -example: 68b329da9893e34099c7d8ad5cb9c940 - --- - -*`package.description`*:: -+ --- -Description of the package. - -type: keyword - -example: Open source programming language to build simple/reliable/efficient software. - --- - -*`package.install_scope`*:: -+ --- -Indicating how the package was installed, e.g. user-local, global. - -type: keyword - -example: global - --- - -*`package.installed`*:: -+ --- -Time when package was installed. - -type: date - --- - -*`package.license`*:: -+ --- -License under which the package was released. -Use a short name, e.g. the license identifier from SPDX License List where possible (https://spdx.org/licenses/). - -type: keyword - -example: Apache License 2.0 - --- - -*`package.name`*:: -+ --- -Package name - -type: keyword - -example: go - --- - -*`package.path`*:: -+ --- -Path where the package is installed. - -type: keyword - -example: /usr/local/Cellar/go/1.12.9/ - --- - -*`package.reference`*:: -+ --- -Home page or reference URL of the software in this package, if available. - -type: keyword - -example: https://golang.org - --- - -*`package.size`*:: -+ --- -Package size in bytes. - -type: long - -example: 62231 - -format: string - --- - -*`package.type`*:: -+ --- -Type of package. -This should contain the package file type, rather than the package manager name. Examples: rpm, dpkg, brew, npm, gem, nupkg, jar. - -type: keyword - -example: rpm - --- - -*`package.version`*:: -+ --- -Package version - -type: keyword - -example: 1.12.9 - --- - -[float] -=== pe - -These fields contain Windows Portable Executable (PE) metadata. - - -*`pe.architecture`*:: -+ --- -CPU architecture target for the file. - -type: keyword - -example: x64 - --- - -*`pe.company`*:: -+ --- -Internal company name of the file, provided at compile-time. - -type: keyword - -example: Microsoft Corporation - --- - -*`pe.description`*:: -+ --- -Internal description of the file, provided at compile-time. - -type: keyword - -example: Paint - --- - -*`pe.file_version`*:: -+ --- -Internal version of the file, provided at compile-time. - -type: keyword - -example: 6.3.9600.17415 - --- - -*`pe.imphash`*:: -+ --- -A hash of the imports in a PE file. An imphash -- or import hash -- can be used to fingerprint binaries even after recompilation or other code-level transformations have occurred, which would change more traditional hash values. -Learn more at https://www.fireeye.com/blog/threat-research/2014/01/tracking-malware-import-hashing.html. - -type: keyword - -example: 0c6803c4e922103c4dca5963aad36ddf - --- - -*`pe.original_file_name`*:: -+ --- -Internal name of the file, provided at compile-time. - -type: keyword - -example: MSPAINT.EXE - --- - -*`pe.product`*:: -+ --- -Internal product name of the file, provided at compile-time. - -type: keyword - -example: Microsoft® Windows® Operating System - --- - -[float] -=== process - -These fields contain information about a process. -These fields can help you correlate metrics information with a process id/name from a log message. The `process.pid` often stays in the metric itself and is copied to the global field for correlation. - - -*`process.args`*:: -+ --- -Array of process arguments, starting with the absolute path to the executable. -May be filtered to protect sensitive information. - -type: keyword - -example: ["/usr/bin/ssh", "-l", "user", "10.0.0.16"] - --- - -*`process.args_count`*:: -+ --- -Length of the process.args array. -This field can be useful for querying or performing bucket analysis on how many arguments were provided to start a process. More arguments may be an indication of suspicious activity. - -type: long - -example: 4 - --- - -*`process.code_signature.digest_algorithm`*:: -+ --- -The hashing algorithm used to sign the process. -This value can distinguish signatures when a file is signed multiple times by the same signer but with a different digest algorithm. - -type: keyword - -example: sha256 - --- - -*`process.code_signature.exists`*:: -+ --- -Boolean to capture if a signature is present. - -type: boolean - -example: true - --- - -*`process.code_signature.signing_id`*:: -+ --- -The identifier used to sign the process. -This is used to identify the application manufactured by a software vendor. The field is relevant to Apple *OS only. - -type: keyword - -example: com.apple.xpc.proxy - --- - -*`process.code_signature.status`*:: -+ --- -Additional information about the certificate status. -This is useful for logging cryptographic errors with the certificate validity or trust status. Leave unpopulated if the validity or trust of the certificate was unchecked. - -type: keyword - -example: ERROR_UNTRUSTED_ROOT - --- - -*`process.code_signature.subject_name`*:: -+ --- -Subject name of the code signer - -type: keyword - -example: Microsoft Corporation - --- - -*`process.code_signature.team_id`*:: -+ --- -The team identifier used to sign the process. -This is used to identify the team or vendor of a software product. The field is relevant to Apple *OS only. - -type: keyword - -example: EQHXZ8M8AV - --- - -*`process.code_signature.timestamp`*:: -+ --- -Date and time when the code signature was generated and signed. - -type: date - -example: 2021-01-01T12:10:30Z - --- - -*`process.code_signature.trusted`*:: -+ --- -Stores the trust status of the certificate chain. -Validating the trust of the certificate chain may be complicated, and this field should only be populated by tools that actively check the status. - -type: boolean - -example: true - --- - -*`process.code_signature.valid`*:: -+ --- -Boolean to capture if the digital signature is verified against the binary content. -Leave unpopulated if a certificate was unchecked. - -type: boolean - -example: true - --- - -*`process.command_line`*:: -+ --- -Full command line that started the process, including the absolute path to the executable, and all arguments. -Some arguments may be filtered to protect sensitive information. - -type: wildcard - -example: /usr/bin/ssh -l user 10.0.0.16 - --- - -*`process.command_line.text`*:: -+ --- -type: match_only_text - --- - -*`process.elf.architecture`*:: -+ --- -Machine architecture of the ELF file. - -type: keyword - -example: x86-64 - --- - -*`process.elf.byte_order`*:: -+ --- -Byte sequence of ELF file. - -type: keyword - -example: Little Endian - --- - -*`process.elf.cpu_type`*:: -+ --- -CPU type of the ELF file. - -type: keyword - -example: Intel - --- - -*`process.elf.creation_date`*:: -+ --- -Extracted when possible from the file's metadata. Indicates when it was built or compiled. It can also be faked by malware creators. - -type: date - --- - -*`process.elf.exports`*:: -+ --- -List of exported element names and types. - -type: flattened - --- - -*`process.elf.header.abi_version`*:: -+ --- -Version of the ELF Application Binary Interface (ABI). - -type: keyword - --- - -*`process.elf.header.class`*:: -+ --- -Header class of the ELF file. - -type: keyword - --- - -*`process.elf.header.data`*:: -+ --- -Data table of the ELF header. - -type: keyword - --- - -*`process.elf.header.entrypoint`*:: -+ --- -Header entrypoint of the ELF file. - -type: long - -format: string - --- - -*`process.elf.header.object_version`*:: -+ --- -"0x1" for original ELF files. - -type: keyword - --- - -*`process.elf.header.os_abi`*:: -+ --- -Application Binary Interface (ABI) of the Linux OS. - -type: keyword - --- - -*`process.elf.header.type`*:: -+ --- -Header type of the ELF file. - -type: keyword - --- - -*`process.elf.header.version`*:: -+ --- -Version of the ELF header. - -type: keyword - --- - -*`process.elf.imports`*:: -+ --- -List of imported element names and types. - -type: flattened - --- - -*`process.elf.sections`*:: -+ --- -An array containing an object for each section of the ELF file. -The keys that should be present in these objects are defined by sub-fields underneath `elf.sections.*`. - -type: nested - --- - -*`process.elf.sections.chi2`*:: -+ --- -Chi-square probability distribution of the section. - -type: long - -format: number - --- - -*`process.elf.sections.entropy`*:: -+ --- -Shannon entropy calculation from the section. - -type: long - -format: number - --- - -*`process.elf.sections.flags`*:: -+ --- -ELF Section List flags. - -type: keyword - --- - -*`process.elf.sections.name`*:: -+ --- -ELF Section List name. - -type: keyword - --- - -*`process.elf.sections.physical_offset`*:: -+ --- -ELF Section List offset. - -type: keyword - --- - -*`process.elf.sections.physical_size`*:: -+ --- -ELF Section List physical size. - -type: long - -format: bytes - --- - -*`process.elf.sections.type`*:: -+ --- -ELF Section List type. - -type: keyword - --- - -*`process.elf.sections.virtual_address`*:: -+ --- -ELF Section List virtual address. - -type: long - -format: string - --- - -*`process.elf.sections.virtual_size`*:: -+ --- -ELF Section List virtual size. - -type: long - -format: string - --- - -*`process.elf.segments`*:: -+ --- -An array containing an object for each segment of the ELF file. -The keys that should be present in these objects are defined by sub-fields underneath `elf.segments.*`. - -type: nested - --- - -*`process.elf.segments.sections`*:: -+ --- -ELF object segment sections. - -type: keyword - --- - -*`process.elf.segments.type`*:: -+ --- -ELF object segment type. - -type: keyword - --- - -*`process.elf.shared_libraries`*:: -+ --- -List of shared libraries used by this ELF object. - -type: keyword - --- - -*`process.elf.telfhash`*:: -+ --- -telfhash symbol hash for ELF file. - -type: keyword - --- - -*`process.end`*:: -+ --- -The time the process ended. - -type: date - -example: 2016-05-23T08:05:34.853Z - --- - -*`process.entity_id`*:: -+ --- -Unique identifier for the process. -The implementation of this is specified by the data source, but some examples of what could be used here are a process-generated UUID, Sysmon Process GUIDs, or a hash of some uniquely identifying components of a process. -Constructing a globally unique identifier is a common practice to mitigate PID reuse as well as to identify a specific process over time, across multiple monitored hosts. - -type: keyword - -example: c2c455d9f99375d - --- - -*`process.executable`*:: -+ --- -Absolute path to the process executable. - -type: keyword - -example: /usr/bin/ssh - --- - -*`process.executable.text`*:: -+ --- -type: match_only_text - --- - -*`process.exit_code`*:: -+ --- -The exit code of the process, if this is a termination event. -The field should be absent if there is no exit code for the event (e.g. process start). - -type: long - -example: 137 - --- - -*`process.hash.md5`*:: -+ --- -MD5 hash. - -type: keyword - --- - -*`process.hash.sha1`*:: -+ --- -SHA1 hash. - -type: keyword - --- - -*`process.hash.sha256`*:: -+ --- -SHA256 hash. - -type: keyword - --- - -*`process.hash.sha512`*:: -+ --- -SHA512 hash. - -type: keyword - --- - -*`process.hash.ssdeep`*:: -+ --- -SSDEEP hash. - -type: keyword - --- - -*`process.name`*:: -+ --- -Process name. -Sometimes called program name or similar. - -type: keyword - -example: ssh - --- - -*`process.name.text`*:: -+ --- -type: match_only_text - --- - -*`process.parent.args`*:: -+ --- -Array of process arguments, starting with the absolute path to the executable. -May be filtered to protect sensitive information. - -type: keyword - -example: ["/usr/bin/ssh", "-l", "user", "10.0.0.16"] - --- - -*`process.parent.args_count`*:: -+ --- -Length of the process.args array. -This field can be useful for querying or performing bucket analysis on how many arguments were provided to start a process. More arguments may be an indication of suspicious activity. - -type: long - -example: 4 - --- - -*`process.parent.code_signature.digest_algorithm`*:: -+ --- -The hashing algorithm used to sign the process. -This value can distinguish signatures when a file is signed multiple times by the same signer but with a different digest algorithm. - -type: keyword - -example: sha256 - --- - -*`process.parent.code_signature.exists`*:: -+ --- -Boolean to capture if a signature is present. - -type: boolean - -example: true - --- - -*`process.parent.code_signature.signing_id`*:: -+ --- -The identifier used to sign the process. -This is used to identify the application manufactured by a software vendor. The field is relevant to Apple *OS only. - -type: keyword - -example: com.apple.xpc.proxy - --- - -*`process.parent.code_signature.status`*:: -+ --- -Additional information about the certificate status. -This is useful for logging cryptographic errors with the certificate validity or trust status. Leave unpopulated if the validity or trust of the certificate was unchecked. - -type: keyword - -example: ERROR_UNTRUSTED_ROOT - --- - -*`process.parent.code_signature.subject_name`*:: -+ --- -Subject name of the code signer - -type: keyword - -example: Microsoft Corporation - --- - -*`process.parent.code_signature.team_id`*:: -+ --- -The team identifier used to sign the process. -This is used to identify the team or vendor of a software product. The field is relevant to Apple *OS only. - -type: keyword - -example: EQHXZ8M8AV - --- - -*`process.parent.code_signature.timestamp`*:: -+ --- -Date and time when the code signature was generated and signed. - -type: date - -example: 2021-01-01T12:10:30Z - --- - -*`process.parent.code_signature.trusted`*:: -+ --- -Stores the trust status of the certificate chain. -Validating the trust of the certificate chain may be complicated, and this field should only be populated by tools that actively check the status. - -type: boolean - -example: true - --- - -*`process.parent.code_signature.valid`*:: -+ --- -Boolean to capture if the digital signature is verified against the binary content. -Leave unpopulated if a certificate was unchecked. - -type: boolean - -example: true - --- - -*`process.parent.command_line`*:: -+ --- -Full command line that started the process, including the absolute path to the executable, and all arguments. -Some arguments may be filtered to protect sensitive information. - -type: wildcard - -example: /usr/bin/ssh -l user 10.0.0.16 - --- - -*`process.parent.command_line.text`*:: -+ --- -type: match_only_text - --- - -*`process.parent.elf.architecture`*:: -+ --- -Machine architecture of the ELF file. - -type: keyword - -example: x86-64 - --- - -*`process.parent.elf.byte_order`*:: -+ --- -Byte sequence of ELF file. - -type: keyword - -example: Little Endian - --- - -*`process.parent.elf.cpu_type`*:: -+ --- -CPU type of the ELF file. - -type: keyword - -example: Intel - --- - -*`process.parent.elf.creation_date`*:: -+ --- -Extracted when possible from the file's metadata. Indicates when it was built or compiled. It can also be faked by malware creators. - -type: date - --- - -*`process.parent.elf.exports`*:: -+ --- -List of exported element names and types. - -type: flattened - --- - -*`process.parent.elf.header.abi_version`*:: -+ --- -Version of the ELF Application Binary Interface (ABI). - -type: keyword - --- - -*`process.parent.elf.header.class`*:: -+ --- -Header class of the ELF file. - -type: keyword - --- - -*`process.parent.elf.header.data`*:: -+ --- -Data table of the ELF header. - -type: keyword - --- - -*`process.parent.elf.header.entrypoint`*:: -+ --- -Header entrypoint of the ELF file. - -type: long - -format: string - --- - -*`process.parent.elf.header.object_version`*:: -+ --- -"0x1" for original ELF files. - -type: keyword - --- - -*`process.parent.elf.header.os_abi`*:: -+ --- -Application Binary Interface (ABI) of the Linux OS. - -type: keyword - --- - -*`process.parent.elf.header.type`*:: -+ --- -Header type of the ELF file. - -type: keyword - --- - -*`process.parent.elf.header.version`*:: -+ --- -Version of the ELF header. - -type: keyword - --- - -*`process.parent.elf.imports`*:: -+ --- -List of imported element names and types. - -type: flattened - --- - -*`process.parent.elf.sections`*:: -+ --- -An array containing an object for each section of the ELF file. -The keys that should be present in these objects are defined by sub-fields underneath `elf.sections.*`. - -type: nested - --- - -*`process.parent.elf.sections.chi2`*:: -+ --- -Chi-square probability distribution of the section. - -type: long - -format: number - --- - -*`process.parent.elf.sections.entropy`*:: -+ --- -Shannon entropy calculation from the section. - -type: long - -format: number - --- - -*`process.parent.elf.sections.flags`*:: -+ --- -ELF Section List flags. - -type: keyword - --- - -*`process.parent.elf.sections.name`*:: -+ --- -ELF Section List name. - -type: keyword - --- - -*`process.parent.elf.sections.physical_offset`*:: -+ --- -ELF Section List offset. - -type: keyword - --- - -*`process.parent.elf.sections.physical_size`*:: -+ --- -ELF Section List physical size. - -type: long - -format: bytes - --- - -*`process.parent.elf.sections.type`*:: -+ --- -ELF Section List type. - -type: keyword - --- - -*`process.parent.elf.sections.virtual_address`*:: -+ --- -ELF Section List virtual address. - -type: long - -format: string - --- - -*`process.parent.elf.sections.virtual_size`*:: -+ --- -ELF Section List virtual size. - -type: long - -format: string - --- - -*`process.parent.elf.segments`*:: -+ --- -An array containing an object for each segment of the ELF file. -The keys that should be present in these objects are defined by sub-fields underneath `elf.segments.*`. - -type: nested - --- - -*`process.parent.elf.segments.sections`*:: -+ --- -ELF object segment sections. - -type: keyword - --- - -*`process.parent.elf.segments.type`*:: -+ --- -ELF object segment type. - -type: keyword - --- - -*`process.parent.elf.shared_libraries`*:: -+ --- -List of shared libraries used by this ELF object. - -type: keyword - --- - -*`process.parent.elf.telfhash`*:: -+ --- -telfhash symbol hash for ELF file. - -type: keyword - --- - -*`process.parent.end`*:: -+ --- -The time the process ended. - -type: date - -example: 2016-05-23T08:05:34.853Z - --- - -*`process.parent.entity_id`*:: -+ --- -Unique identifier for the process. -The implementation of this is specified by the data source, but some examples of what could be used here are a process-generated UUID, Sysmon Process GUIDs, or a hash of some uniquely identifying components of a process. -Constructing a globally unique identifier is a common practice to mitigate PID reuse as well as to identify a specific process over time, across multiple monitored hosts. - -type: keyword - -example: c2c455d9f99375d - --- - -*`process.parent.executable`*:: -+ --- -Absolute path to the process executable. - -type: keyword - -example: /usr/bin/ssh - --- - -*`process.parent.executable.text`*:: -+ --- -type: match_only_text - --- - -*`process.parent.exit_code`*:: -+ --- -The exit code of the process, if this is a termination event. -The field should be absent if there is no exit code for the event (e.g. process start). - -type: long - -example: 137 - --- - -*`process.parent.hash.md5`*:: -+ --- -MD5 hash. - -type: keyword - --- - -*`process.parent.hash.sha1`*:: -+ --- -SHA1 hash. - -type: keyword - --- - -*`process.parent.hash.sha256`*:: -+ --- -SHA256 hash. - -type: keyword - --- - -*`process.parent.hash.sha512`*:: -+ --- -SHA512 hash. - -type: keyword - --- - -*`process.parent.hash.ssdeep`*:: -+ --- -SSDEEP hash. - -type: keyword - --- - -*`process.parent.name`*:: -+ --- -Process name. -Sometimes called program name or similar. - -type: keyword - -example: ssh - --- - -*`process.parent.name.text`*:: -+ --- -type: match_only_text - --- - -*`process.parent.pe.architecture`*:: -+ --- -CPU architecture target for the file. - -type: keyword - -example: x64 - --- - -*`process.parent.pe.company`*:: -+ --- -Internal company name of the file, provided at compile-time. - -type: keyword - -example: Microsoft Corporation - --- - -*`process.parent.pe.description`*:: -+ --- -Internal description of the file, provided at compile-time. - -type: keyword - -example: Paint - --- - -*`process.parent.pe.file_version`*:: -+ --- -Internal version of the file, provided at compile-time. - -type: keyword - -example: 6.3.9600.17415 - --- - -*`process.parent.pe.imphash`*:: -+ --- -A hash of the imports in a PE file. An imphash -- or import hash -- can be used to fingerprint binaries even after recompilation or other code-level transformations have occurred, which would change more traditional hash values. -Learn more at https://www.fireeye.com/blog/threat-research/2014/01/tracking-malware-import-hashing.html. - -type: keyword - -example: 0c6803c4e922103c4dca5963aad36ddf - --- - -*`process.parent.pe.original_file_name`*:: -+ --- -Internal name of the file, provided at compile-time. - -type: keyword - -example: MSPAINT.EXE - --- - -*`process.parent.pe.product`*:: -+ --- -Internal product name of the file, provided at compile-time. - -type: keyword - -example: Microsoft® Windows® Operating System - --- - -*`process.parent.pgid`*:: -+ --- -Identifier of the group of processes the process belongs to. - -type: long - -format: string - --- - -*`process.parent.pid`*:: -+ --- -Process id. - -type: long - -example: 4242 - -format: string - --- - -*`process.parent.start`*:: -+ --- -The time the process started. - -type: date - -example: 2016-05-23T08:05:34.853Z - --- - -*`process.parent.thread.id`*:: -+ --- -Thread ID. - -type: long - -example: 4242 - -format: string - --- - -*`process.parent.thread.name`*:: -+ --- -Thread name. - -type: keyword - -example: thread-0 - --- - -*`process.parent.title`*:: -+ --- -Process title. -The proctitle, some times the same as process name. Can also be different: for example a browser setting its title to the web page currently opened. - -type: keyword - --- - -*`process.parent.title.text`*:: -+ --- -type: match_only_text - --- - -*`process.parent.uptime`*:: -+ --- -Seconds the process has been up. - -type: long - -example: 1325 - --- - -*`process.parent.working_directory`*:: -+ --- -The working directory of the process. - -type: keyword - -example: /home/alice - --- - -*`process.parent.working_directory.text`*:: -+ --- -type: match_only_text - --- - -*`process.pe.architecture`*:: -+ --- -CPU architecture target for the file. - -type: keyword - -example: x64 - --- - -*`process.pe.company`*:: -+ --- -Internal company name of the file, provided at compile-time. - -type: keyword - -example: Microsoft Corporation - --- - -*`process.pe.description`*:: -+ --- -Internal description of the file, provided at compile-time. - -type: keyword - -example: Paint - --- - -*`process.pe.file_version`*:: -+ --- -Internal version of the file, provided at compile-time. - -type: keyword - -example: 6.3.9600.17415 - --- - -*`process.pe.imphash`*:: -+ --- -A hash of the imports in a PE file. An imphash -- or import hash -- can be used to fingerprint binaries even after recompilation or other code-level transformations have occurred, which would change more traditional hash values. -Learn more at https://www.fireeye.com/blog/threat-research/2014/01/tracking-malware-import-hashing.html. - -type: keyword - -example: 0c6803c4e922103c4dca5963aad36ddf - --- - -*`process.pe.original_file_name`*:: -+ --- -Internal name of the file, provided at compile-time. - -type: keyword - -example: MSPAINT.EXE - --- - -*`process.pe.product`*:: -+ --- -Internal product name of the file, provided at compile-time. - -type: keyword - -example: Microsoft® Windows® Operating System - --- - -*`process.pgid`*:: -+ --- -Identifier of the group of processes the process belongs to. - -type: long - -format: string - --- - -*`process.pid`*:: -+ --- -Process id. - -type: long - -example: 4242 - -format: string - --- - -*`process.start`*:: -+ --- -The time the process started. - -type: date - -example: 2016-05-23T08:05:34.853Z - --- - -*`process.thread.id`*:: -+ --- -Thread ID. - -type: long - -example: 4242 - -format: string - --- - -*`process.thread.name`*:: -+ --- -Thread name. - -type: keyword - -example: thread-0 - --- - -*`process.title`*:: -+ --- -Process title. -The proctitle, some times the same as process name. Can also be different: for example a browser setting its title to the web page currently opened. - -type: keyword - --- - -*`process.title.text`*:: -+ --- -type: match_only_text - --- - -*`process.uptime`*:: -+ --- -Seconds the process has been up. - -type: long - -example: 1325 - --- - -*`process.working_directory`*:: -+ --- -The working directory of the process. - -type: keyword - -example: /home/alice - --- - -*`process.working_directory.text`*:: -+ --- -type: match_only_text - --- - -[float] -=== registry - -Fields related to Windows Registry operations. - - -*`registry.data.bytes`*:: -+ --- -Original bytes written with base64 encoding. -For Windows registry operations, such as SetValueEx and RegQueryValueEx, this corresponds to the data pointed by `lp_data`. This is optional but provides better recoverability and should be populated for REG_BINARY encoded values. - -type: keyword - -example: ZQBuAC0AVQBTAAAAZQBuAAAAAAA= - --- - -*`registry.data.strings`*:: -+ --- -Content when writing string types. -Populated as an array when writing string data to the registry. For single string registry types (REG_SZ, REG_EXPAND_SZ), this should be an array with one string. For sequences of string with REG_MULTI_SZ, this array will be variable length. For numeric data, such as REG_DWORD and REG_QWORD, this should be populated with the decimal representation (e.g `"1"`). - -type: wildcard - -example: ["C:\rta\red_ttp\bin\myapp.exe"] - --- - -*`registry.data.type`*:: -+ --- -Standard registry type for encoding contents - -type: keyword - -example: REG_SZ - --- - -*`registry.hive`*:: -+ --- -Abbreviated name for the hive. - -type: keyword - -example: HKLM - --- - -*`registry.key`*:: -+ --- -Hive-relative path of keys. - -type: keyword - -example: SOFTWARE\Microsoft\Windows NT\CurrentVersion\Image File Execution Options\winword.exe - --- - -*`registry.path`*:: -+ --- -Full path, including hive, key and value - -type: keyword - -example: HKLM\SOFTWARE\Microsoft\Windows NT\CurrentVersion\Image File Execution Options\winword.exe\Debugger - --- - -*`registry.value`*:: -+ --- -Name of the value written. - -type: keyword - -example: Debugger - --- - -[float] -=== related - -This field set is meant to facilitate pivoting around a piece of data. -Some pieces of information can be seen in many places in an ECS event. To facilitate searching for them, store an array of all seen values to their corresponding field in `related.`. -A concrete example is IP addresses, which can be under host, observer, source, destination, client, server, and network.forwarded_ip. If you append all IPs to `related.ip`, you can then search for a given IP trivially, no matter where it appeared, by querying `related.ip:192.0.2.15`. - - -*`related.hash`*:: -+ --- -All the hashes seen on your event. Populating this field, then using it to search for hashes can help in situations where you're unsure what the hash algorithm is (and therefore which key name to search). - -type: keyword - --- - -*`related.hosts`*:: -+ --- -All hostnames or other host identifiers seen on your event. Example identifiers include FQDNs, domain names, workstation names, or aliases. - -type: keyword - --- - -*`related.ip`*:: -+ --- -All of the IPs seen on your event. - -type: ip - --- - -*`related.user`*:: -+ --- -All the user names or other user identifiers seen on the event. - -type: keyword - --- - -[float] -=== rule - -Rule fields are used to capture the specifics of any observer or agent rules that generate alerts or other notable events. -Examples of data sources that would populate the rule fields include: network admission control platforms, network or host IDS/IPS, network firewalls, web application firewalls, url filters, endpoint detection and response (EDR) systems, etc. - - -*`rule.author`*:: -+ --- -Name, organization, or pseudonym of the author or authors who created the rule used to generate this event. - -type: keyword - -example: ["Star-Lord"] - --- - -*`rule.category`*:: -+ --- -A categorization value keyword used by the entity using the rule for detection of this event. - -type: keyword - -example: Attempted Information Leak - --- - -*`rule.description`*:: -+ --- -The description of the rule generating the event. - -type: keyword - -example: Block requests to public DNS over HTTPS / TLS protocols - --- - -*`rule.id`*:: -+ --- -A rule ID that is unique within the scope of an agent, observer, or other entity using the rule for detection of this event. - -type: keyword - -example: 101 - --- - -*`rule.license`*:: -+ --- -Name of the license under which the rule used to generate this event is made available. - -type: keyword - -example: Apache 2.0 - --- - -*`rule.name`*:: -+ --- -The name of the rule or signature generating the event. - -type: keyword - -example: BLOCK_DNS_over_TLS - --- - -*`rule.reference`*:: -+ --- -Reference URL to additional information about the rule used to generate this event. -The URL can point to the vendor's documentation about the rule. If that's not available, it can also be a link to a more general page describing this type of alert. - -type: keyword - -example: https://en.wikipedia.org/wiki/DNS_over_TLS - --- - -*`rule.ruleset`*:: -+ --- -Name of the ruleset, policy, group, or parent category in which the rule used to generate this event is a member. - -type: keyword - -example: Standard_Protocol_Filters - --- - -*`rule.uuid`*:: -+ --- -A rule ID that is unique within the scope of a set or group of agents, observers, or other entities using the rule for detection of this event. - -type: keyword - -example: 1100110011 - --- - -*`rule.version`*:: -+ --- -The version / revision of the rule being used for analysis. - -type: keyword - -example: 1.1 - --- - -[float] -=== server - -A Server is defined as the responder in a network connection for events regarding sessions, connections, or bidirectional flow records. -For TCP events, the server is the receiver of the initial SYN packet(s) of the TCP connection. For other protocols, the server is generally the responder in the network transaction. Some systems actually use the term "responder" to refer the server in TCP connections. The server fields describe details about the system acting as the server in the network event. Server fields are usually populated in conjunction with client fields. Server fields are generally not populated for packet-level events. -Client / server representations can add semantic context to an exchange, which is helpful to visualize the data in certain situations. If your context falls in that category, you should still ensure that source and destination are filled appropriately. - - -*`server.address`*:: -+ --- -Some event server addresses are defined ambiguously. The event will sometimes list an IP, a domain or a unix socket. You should always store the raw address in the `.address` field. -Then it should be duplicated to `.ip` or `.domain`, depending on which one it is. - -type: keyword - --- - -*`server.as.number`*:: -+ --- -Unique number allocated to the autonomous system. The autonomous system number (ASN) uniquely identifies each network on the Internet. - -type: long - -example: 15169 - --- - -*`server.as.organization.name`*:: -+ --- -Organization name. - -type: keyword - -example: Google LLC - --- - -*`server.as.organization.name.text`*:: -+ --- -type: match_only_text - --- - -*`server.bytes`*:: -+ --- -Bytes sent from the server to the client. - -type: long - -example: 184 - -format: bytes - --- - -*`server.domain`*:: -+ --- -The domain name of the server system. -This value may be a host name, a fully qualified domain name, or another host naming format. The value may derive from the original event or be added from enrichment. - -type: keyword - -example: foo.example.com - --- - -*`server.geo.city_name`*:: -+ --- -City name. - -type: keyword - -example: Montreal - --- - -*`server.geo.continent_code`*:: -+ --- -Two-letter code representing continent's name. - -type: keyword - -example: NA - --- - -*`server.geo.continent_name`*:: -+ --- -Name of the continent. - -type: keyword - -example: North America - --- - -*`server.geo.country_iso_code`*:: -+ --- -Country ISO code. - -type: keyword - -example: CA - --- - -*`server.geo.country_name`*:: -+ --- -Country name. - -type: keyword - -example: Canada - --- - -*`server.geo.location`*:: -+ --- -Longitude and latitude. - -type: geo_point - -example: { "lon": -73.614830, "lat": 45.505918 } - --- - -*`server.geo.name`*:: -+ --- -User-defined description of a location, at the level of granularity they care about. -Could be the name of their data centers, the floor number, if this describes a local physical entity, city names. -Not typically used in automated geolocation. - -type: keyword - -example: boston-dc - --- - -*`server.geo.postal_code`*:: -+ --- -Postal code associated with the location. -Values appropriate for this field may also be known as a postcode or ZIP code and will vary widely from country to country. - -type: keyword - -example: 94040 - --- - -*`server.geo.region_iso_code`*:: -+ --- -Region ISO code. - -type: keyword - -example: CA-QC - --- - -*`server.geo.region_name`*:: -+ --- -Region name. - -type: keyword - -example: Quebec - --- - -*`server.geo.timezone`*:: -+ --- -The time zone of the location, such as IANA time zone name. - -type: keyword - -example: America/Argentina/Buenos_Aires - --- - -*`server.ip`*:: -+ --- -IP address of the server (IPv4 or IPv6). - -type: ip - --- - -*`server.mac`*:: -+ --- -MAC address of the server. -The notation format from RFC 7042 is suggested: Each octet (that is, 8-bit byte) is represented by two [uppercase] hexadecimal digits giving the value of the octet as an unsigned integer. Successive octets are separated by a hyphen. - -type: keyword - -example: 00-00-5E-00-53-23 - --- - -*`server.nat.ip`*:: -+ --- -Translated ip of destination based NAT sessions (e.g. internet to private DMZ) -Typically used with load balancers, firewalls, or routers. - -type: ip - --- - -*`server.nat.port`*:: -+ --- -Translated port of destination based NAT sessions (e.g. internet to private DMZ) -Typically used with load balancers, firewalls, or routers. - -type: long - -format: string - --- - -*`server.packets`*:: -+ --- -Packets sent from the server to the client. - -type: long - -example: 12 - --- - -*`server.port`*:: -+ --- -Port of the server. - -type: long - -format: string - --- - -*`server.registered_domain`*:: -+ --- -The highest registered server domain, stripped of the subdomain. -For example, the registered domain for "foo.example.com" is "example.com". -This value can be determined precisely with a list like the public suffix list (http://publicsuffix.org). Trying to approximate this by simply taking the last two labels will not work well for TLDs such as "co.uk". - -type: keyword - -example: example.com - --- - -*`server.subdomain`*:: -+ --- -The subdomain portion of a fully qualified domain name includes all of the names except the host name under the registered_domain. In a partially qualified domain, or if the the qualification level of the full name cannot be determined, subdomain contains all of the names below the registered domain. -For example the subdomain portion of "www.east.mydomain.co.uk" is "east". If the domain has multiple levels of subdomain, such as "sub2.sub1.example.com", the subdomain field should contain "sub2.sub1", with no trailing period. - -type: keyword - -example: east - --- - -*`server.top_level_domain`*:: -+ --- -The effective top level domain (eTLD), also known as the domain suffix, is the last part of the domain name. For example, the top level domain for example.com is "com". -This value can be determined precisely with a list like the public suffix list (http://publicsuffix.org). Trying to approximate this by simply taking the last label will not work well for effective TLDs such as "co.uk". - -type: keyword - -example: co.uk - --- - -*`server.user.domain`*:: -+ --- -Name of the directory the user is a member of. -For example, an LDAP or Active Directory domain name. - -type: keyword - --- - -*`server.user.email`*:: -+ --- -User email address. - -type: keyword - --- - -*`server.user.full_name`*:: -+ --- -User's full name, if available. - -type: keyword - -example: Albert Einstein - --- - -*`server.user.full_name.text`*:: -+ --- -type: match_only_text - --- - -*`server.user.group.domain`*:: -+ --- -Name of the directory the group is a member of. -For example, an LDAP or Active Directory domain name. - -type: keyword - --- - -*`server.user.group.id`*:: -+ --- -Unique identifier for the group on the system/platform. - -type: keyword - --- - -*`server.user.group.name`*:: -+ --- -Name of the group. - -type: keyword - --- - -*`server.user.hash`*:: -+ --- -Unique user hash to correlate information for a user in anonymized form. -Useful if `user.id` or `user.name` contain confidential information and cannot be used. - -type: keyword - --- - -*`server.user.id`*:: -+ --- -Unique identifier of the user. - -type: keyword - -example: S-1-5-21-202424912787-2692429404-2351956786-1000 - --- - -*`server.user.name`*:: -+ --- -Short name or login of the user. - -type: keyword - -example: a.einstein - --- - -*`server.user.name.text`*:: -+ --- -type: match_only_text - --- - -*`server.user.roles`*:: -+ --- -Array of user roles at the time of the event. - -type: keyword - -example: ["kibana_admin", "reporting_user"] - --- - -[float] -=== service - -The service fields describe the service for or from which the data was collected. -These fields help you find and correlate logs for a specific service and version. - - -*`service.address`*:: -+ --- -Address where data about this service was collected from. -This should be a URI, network address (ipv4:port or [ipv6]:port) or a resource path (sockets). - -type: keyword - -example: 172.26.0.2:5432 - --- - -*`service.environment`*:: -+ --- -Identifies the environment where the service is running. -If the same service runs in different environments (production, staging, QA, development, etc.), the environment can identify other instances of the same service. Can also group services and applications from the same environment. - -type: keyword - -example: production - --- - -*`service.ephemeral_id`*:: -+ --- -Ephemeral identifier of this service (if one exists). -This id normally changes across restarts, but `service.id` does not. - -type: keyword - -example: 8a4f500f - --- - -*`service.id`*:: -+ --- -Unique identifier of the running service. If the service is comprised of many nodes, the `service.id` should be the same for all nodes. -This id should uniquely identify the service. This makes it possible to correlate logs and metrics for one specific service, no matter which particular node emitted the event. -Note that if you need to see the events from one specific host of the service, you should filter on that `host.name` or `host.id` instead. - -type: keyword - -example: d37e5ebfe0ae6c4972dbe9f0174a1637bb8247f6 - --- - -*`service.name`*:: -+ --- -Name of the service data is collected from. -The name of the service is normally user given. This allows for distributed services that run on multiple hosts to correlate the related instances based on the name. -In the case of Elasticsearch the `service.name` could contain the cluster name. For Beats the `service.name` is by default a copy of the `service.type` field if no name is specified. - -type: keyword - -example: elasticsearch-metrics - --- - -*`service.node.name`*:: -+ --- -Name of a service node. -This allows for two nodes of the same service running on the same host to be differentiated. Therefore, `service.node.name` should typically be unique across nodes of a given service. -In the case of Elasticsearch, the `service.node.name` could contain the unique node name within the Elasticsearch cluster. In cases where the service doesn't have the concept of a node name, the host name or container name can be used to distinguish running instances that make up this service. If those do not provide uniqueness (e.g. multiple instances of the service running on the same host) - the node name can be manually set. - -type: keyword - -example: instance-0000000016 - --- - -*`service.origin.address`*:: -+ --- -Address where data about this service was collected from. -This should be a URI, network address (ipv4:port or [ipv6]:port) or a resource path (sockets). - -type: keyword - -example: 172.26.0.2:5432 - --- - -*`service.origin.environment`*:: -+ --- -Identifies the environment where the service is running. -If the same service runs in different environments (production, staging, QA, development, etc.), the environment can identify other instances of the same service. Can also group services and applications from the same environment. - -type: keyword - -example: production - --- - -*`service.origin.ephemeral_id`*:: -+ --- -Ephemeral identifier of this service (if one exists). -This id normally changes across restarts, but `service.id` does not. - -type: keyword - -example: 8a4f500f - --- - -*`service.origin.id`*:: -+ --- -Unique identifier of the running service. If the service is comprised of many nodes, the `service.id` should be the same for all nodes. -This id should uniquely identify the service. This makes it possible to correlate logs and metrics for one specific service, no matter which particular node emitted the event. -Note that if you need to see the events from one specific host of the service, you should filter on that `host.name` or `host.id` instead. - -type: keyword - -example: d37e5ebfe0ae6c4972dbe9f0174a1637bb8247f6 - --- - -*`service.origin.name`*:: -+ --- -Name of the service data is collected from. -The name of the service is normally user given. This allows for distributed services that run on multiple hosts to correlate the related instances based on the name. -In the case of Elasticsearch the `service.name` could contain the cluster name. For Beats the `service.name` is by default a copy of the `service.type` field if no name is specified. - -type: keyword - -example: elasticsearch-metrics - --- - -*`service.origin.node.name`*:: -+ --- -Name of a service node. -This allows for two nodes of the same service running on the same host to be differentiated. Therefore, `service.node.name` should typically be unique across nodes of a given service. -In the case of Elasticsearch, the `service.node.name` could contain the unique node name within the Elasticsearch cluster. In cases where the service doesn't have the concept of a node name, the host name or container name can be used to distinguish running instances that make up this service. If those do not provide uniqueness (e.g. multiple instances of the service running on the same host) - the node name can be manually set. - -type: keyword - -example: instance-0000000016 - --- - -*`service.origin.state`*:: -+ --- -Current state of the service. - -type: keyword - --- - -*`service.origin.type`*:: -+ --- -The type of the service data is collected from. -The type can be used to group and correlate logs and metrics from one service type. -Example: If logs or metrics are collected from Elasticsearch, `service.type` would be `elasticsearch`. - -type: keyword - -example: elasticsearch - --- - -*`service.origin.version`*:: -+ --- -Version of the service the data was collected from. -This allows to look at a data set only for a specific version of a service. - -type: keyword - -example: 3.2.4 - --- - -*`service.state`*:: -+ --- -Current state of the service. - -type: keyword - --- - -*`service.target.address`*:: -+ --- -Address where data about this service was collected from. -This should be a URI, network address (ipv4:port or [ipv6]:port) or a resource path (sockets). - -type: keyword - -example: 172.26.0.2:5432 - --- - -*`service.target.environment`*:: -+ --- -Identifies the environment where the service is running. -If the same service runs in different environments (production, staging, QA, development, etc.), the environment can identify other instances of the same service. Can also group services and applications from the same environment. - -type: keyword - -example: production - --- - -*`service.target.ephemeral_id`*:: -+ --- -Ephemeral identifier of this service (if one exists). -This id normally changes across restarts, but `service.id` does not. - -type: keyword - -example: 8a4f500f - --- - -*`service.target.id`*:: -+ --- -Unique identifier of the running service. If the service is comprised of many nodes, the `service.id` should be the same for all nodes. -This id should uniquely identify the service. This makes it possible to correlate logs and metrics for one specific service, no matter which particular node emitted the event. -Note that if you need to see the events from one specific host of the service, you should filter on that `host.name` or `host.id` instead. - -type: keyword - -example: d37e5ebfe0ae6c4972dbe9f0174a1637bb8247f6 - --- - -*`service.target.name`*:: -+ --- -Name of the service data is collected from. -The name of the service is normally user given. This allows for distributed services that run on multiple hosts to correlate the related instances based on the name. -In the case of Elasticsearch the `service.name` could contain the cluster name. For Beats the `service.name` is by default a copy of the `service.type` field if no name is specified. - -type: keyword - -example: elasticsearch-metrics - --- - -*`service.target.node.name`*:: -+ --- -Name of a service node. -This allows for two nodes of the same service running on the same host to be differentiated. Therefore, `service.node.name` should typically be unique across nodes of a given service. -In the case of Elasticsearch, the `service.node.name` could contain the unique node name within the Elasticsearch cluster. In cases where the service doesn't have the concept of a node name, the host name or container name can be used to distinguish running instances that make up this service. If those do not provide uniqueness (e.g. multiple instances of the service running on the same host) - the node name can be manually set. - -type: keyword - -example: instance-0000000016 - --- - -*`service.target.state`*:: -+ --- -Current state of the service. - -type: keyword - --- - -*`service.target.type`*:: -+ --- -The type of the service data is collected from. -The type can be used to group and correlate logs and metrics from one service type. -Example: If logs or metrics are collected from Elasticsearch, `service.type` would be `elasticsearch`. - -type: keyword - -example: elasticsearch - --- - -*`service.target.version`*:: -+ --- -Version of the service the data was collected from. -This allows to look at a data set only for a specific version of a service. - -type: keyword - -example: 3.2.4 - --- - -*`service.type`*:: -+ --- -The type of the service data is collected from. -The type can be used to group and correlate logs and metrics from one service type. -Example: If logs or metrics are collected from Elasticsearch, `service.type` would be `elasticsearch`. - -type: keyword - -example: elasticsearch - --- - -*`service.version`*:: -+ --- -Version of the service the data was collected from. -This allows to look at a data set only for a specific version of a service. - -type: keyword - -example: 3.2.4 - --- - -[float] -=== source - -Source fields capture details about the sender of a network exchange/packet. These fields are populated from a network event, packet, or other event containing details of a network transaction. -Source fields are usually populated in conjunction with destination fields. The source and destination fields are considered the baseline and should always be filled if an event contains source and destination details from a network transaction. If the event also contains identification of the client and server roles, then the client and server fields should also be populated. - - -*`source.address`*:: -+ --- -Some event source addresses are defined ambiguously. The event will sometimes list an IP, a domain or a unix socket. You should always store the raw address in the `.address` field. -Then it should be duplicated to `.ip` or `.domain`, depending on which one it is. - -type: keyword - --- - -*`source.as.number`*:: -+ --- -Unique number allocated to the autonomous system. The autonomous system number (ASN) uniquely identifies each network on the Internet. - -type: long - -example: 15169 - --- - -*`source.as.organization.name`*:: -+ --- -Organization name. - -type: keyword - -example: Google LLC - --- - -*`source.as.organization.name.text`*:: -+ --- -type: match_only_text - --- - -*`source.bytes`*:: -+ --- -Bytes sent from the source to the destination. - -type: long - -example: 184 - -format: bytes - --- - -*`source.domain`*:: -+ --- -The domain name of the source system. -This value may be a host name, a fully qualified domain name, or another host naming format. The value may derive from the original event or be added from enrichment. - -type: keyword - -example: foo.example.com - --- - -*`source.geo.city_name`*:: -+ --- -City name. - -type: keyword - -example: Montreal - --- - -*`source.geo.continent_code`*:: -+ --- -Two-letter code representing continent's name. - -type: keyword - -example: NA - --- - -*`source.geo.continent_name`*:: -+ --- -Name of the continent. - -type: keyword - -example: North America - --- - -*`source.geo.country_iso_code`*:: -+ --- -Country ISO code. - -type: keyword - -example: CA - --- - -*`source.geo.country_name`*:: -+ --- -Country name. - -type: keyword - -example: Canada - --- - -*`source.geo.location`*:: -+ --- -Longitude and latitude. - -type: geo_point - -example: { "lon": -73.614830, "lat": 45.505918 } - --- - -*`source.geo.name`*:: -+ --- -User-defined description of a location, at the level of granularity they care about. -Could be the name of their data centers, the floor number, if this describes a local physical entity, city names. -Not typically used in automated geolocation. - -type: keyword - -example: boston-dc - --- - -*`source.geo.postal_code`*:: -+ --- -Postal code associated with the location. -Values appropriate for this field may also be known as a postcode or ZIP code and will vary widely from country to country. - -type: keyword - -example: 94040 - --- - -*`source.geo.region_iso_code`*:: -+ --- -Region ISO code. - -type: keyword - -example: CA-QC - --- - -*`source.geo.region_name`*:: -+ --- -Region name. - -type: keyword - -example: Quebec - --- - -*`source.geo.timezone`*:: -+ --- -The time zone of the location, such as IANA time zone name. - -type: keyword - -example: America/Argentina/Buenos_Aires - --- - -*`source.ip`*:: -+ --- -IP address of the source (IPv4 or IPv6). - -type: ip - --- - -*`source.mac`*:: -+ --- -MAC address of the source. -The notation format from RFC 7042 is suggested: Each octet (that is, 8-bit byte) is represented by two [uppercase] hexadecimal digits giving the value of the octet as an unsigned integer. Successive octets are separated by a hyphen. - -type: keyword - -example: 00-00-5E-00-53-23 - --- - -*`source.nat.ip`*:: -+ --- -Translated ip of source based NAT sessions (e.g. internal client to internet) -Typically connections traversing load balancers, firewalls, or routers. - -type: ip - --- - -*`source.nat.port`*:: -+ --- -Translated port of source based NAT sessions. (e.g. internal client to internet) -Typically used with load balancers, firewalls, or routers. - -type: long - -format: string - --- - -*`source.packets`*:: -+ --- -Packets sent from the source to the destination. - -type: long - -example: 12 - --- - -*`source.port`*:: -+ --- -Port of the source. - -type: long - -format: string - --- - -*`source.registered_domain`*:: -+ --- -The highest registered source domain, stripped of the subdomain. -For example, the registered domain for "foo.example.com" is "example.com". -This value can be determined precisely with a list like the public suffix list (http://publicsuffix.org). Trying to approximate this by simply taking the last two labels will not work well for TLDs such as "co.uk". - -type: keyword - -example: example.com - --- - -*`source.subdomain`*:: -+ --- -The subdomain portion of a fully qualified domain name includes all of the names except the host name under the registered_domain. In a partially qualified domain, or if the the qualification level of the full name cannot be determined, subdomain contains all of the names below the registered domain. -For example the subdomain portion of "www.east.mydomain.co.uk" is "east". If the domain has multiple levels of subdomain, such as "sub2.sub1.example.com", the subdomain field should contain "sub2.sub1", with no trailing period. - -type: keyword - -example: east - --- - -*`source.top_level_domain`*:: -+ --- -The effective top level domain (eTLD), also known as the domain suffix, is the last part of the domain name. For example, the top level domain for example.com is "com". -This value can be determined precisely with a list like the public suffix list (http://publicsuffix.org). Trying to approximate this by simply taking the last label will not work well for effective TLDs such as "co.uk". - -type: keyword - -example: co.uk - --- - -*`source.user.domain`*:: -+ --- -Name of the directory the user is a member of. -For example, an LDAP or Active Directory domain name. - -type: keyword - --- - -*`source.user.email`*:: -+ --- -User email address. - -type: keyword - --- - -*`source.user.full_name`*:: -+ --- -User's full name, if available. - -type: keyword - -example: Albert Einstein - --- - -*`source.user.full_name.text`*:: -+ --- -type: match_only_text - --- - -*`source.user.group.domain`*:: -+ --- -Name of the directory the group is a member of. -For example, an LDAP or Active Directory domain name. - -type: keyword - --- - -*`source.user.group.id`*:: -+ --- -Unique identifier for the group on the system/platform. - -type: keyword - --- - -*`source.user.group.name`*:: -+ --- -Name of the group. - -type: keyword - --- - -*`source.user.hash`*:: -+ --- -Unique user hash to correlate information for a user in anonymized form. -Useful if `user.id` or `user.name` contain confidential information and cannot be used. - -type: keyword - --- - -*`source.user.id`*:: -+ --- -Unique identifier of the user. - -type: keyword - -example: S-1-5-21-202424912787-2692429404-2351956786-1000 - --- - -*`source.user.name`*:: -+ --- -Short name or login of the user. - -type: keyword - -example: a.einstein - --- - -*`source.user.name.text`*:: -+ --- -type: match_only_text - --- - -*`source.user.roles`*:: -+ --- -Array of user roles at the time of the event. - -type: keyword - -example: ["kibana_admin", "reporting_user"] - --- - -[float] -=== threat - -Fields to classify events and alerts according to a threat taxonomy such as the MITRE ATT&CK® framework. -These fields are for users to classify alerts from all of their sources (e.g. IDS, NGFW, etc.) within a common taxonomy. The threat.tactic.* fields are meant to capture the high level category of the threat (e.g. "impact"). The threat.technique.* fields are meant to capture which kind of approach is used by this detected threat, to accomplish the goal (e.g. "endpoint denial of service"). - - -*`threat.enrichments`*:: -+ --- -A list of associated indicators objects enriching the event, and the context of that association/enrichment. - -type: nested - --- - -*`threat.enrichments.indicator`*:: -+ --- -Object containing associated indicators enriching the event. - -type: object - --- - -*`threat.enrichments.indicator.as.number`*:: -+ --- -Unique number allocated to the autonomous system. The autonomous system number (ASN) uniquely identifies each network on the Internet. - -type: long - -example: 15169 - --- - -*`threat.enrichments.indicator.as.organization.name`*:: -+ --- -Organization name. - -type: keyword - -example: Google LLC - --- - -*`threat.enrichments.indicator.as.organization.name.text`*:: -+ --- -type: match_only_text - --- - -*`threat.enrichments.indicator.confidence`*:: -+ --- -Identifies the vendor-neutral confidence rating using the None/Low/Medium/High scale defined in Appendix A of the STIX 2.1 framework. Vendor-specific confidence scales may be added as custom fields. -Expected values are: - * Not Specified - * None - * Low - * Medium - * High - -type: keyword - -example: Medium - --- - -*`threat.enrichments.indicator.description`*:: -+ --- -Describes the type of action conducted by the threat. - -type: keyword - -example: IP x.x.x.x was observed delivering the Angler EK. - --- - -*`threat.enrichments.indicator.email.address`*:: -+ --- -Identifies a threat indicator as an email address (irrespective of direction). - -type: keyword - -example: phish@example.com - --- - -*`threat.enrichments.indicator.file.accessed`*:: -+ --- -Last time the file was accessed. -Note that not all filesystems keep track of access time. - -type: date - --- - -*`threat.enrichments.indicator.file.attributes`*:: -+ --- -Array of file attributes. -Attributes names will vary by platform. Here's a non-exhaustive list of values that are expected in this field: archive, compressed, directory, encrypted, execute, hidden, read, readonly, system, write. - -type: keyword - -example: ["readonly", "system"] - --- - -*`threat.enrichments.indicator.file.code_signature.digest_algorithm`*:: -+ --- -The hashing algorithm used to sign the process. -This value can distinguish signatures when a file is signed multiple times by the same signer but with a different digest algorithm. - -type: keyword - -example: sha256 - --- - -*`threat.enrichments.indicator.file.code_signature.exists`*:: -+ --- -Boolean to capture if a signature is present. - -type: boolean - -example: true - --- - -*`threat.enrichments.indicator.file.code_signature.signing_id`*:: -+ --- -The identifier used to sign the process. -This is used to identify the application manufactured by a software vendor. The field is relevant to Apple *OS only. - -type: keyword - -example: com.apple.xpc.proxy - --- - -*`threat.enrichments.indicator.file.code_signature.status`*:: -+ --- -Additional information about the certificate status. -This is useful for logging cryptographic errors with the certificate validity or trust status. Leave unpopulated if the validity or trust of the certificate was unchecked. - -type: keyword - -example: ERROR_UNTRUSTED_ROOT - --- - -*`threat.enrichments.indicator.file.code_signature.subject_name`*:: -+ --- -Subject name of the code signer - -type: keyword - -example: Microsoft Corporation - --- - -*`threat.enrichments.indicator.file.code_signature.team_id`*:: -+ --- -The team identifier used to sign the process. -This is used to identify the team or vendor of a software product. The field is relevant to Apple *OS only. - -type: keyword - -example: EQHXZ8M8AV - --- - -*`threat.enrichments.indicator.file.code_signature.timestamp`*:: -+ --- -Date and time when the code signature was generated and signed. - -type: date - -example: 2021-01-01T12:10:30Z - --- - -*`threat.enrichments.indicator.file.code_signature.trusted`*:: -+ --- -Stores the trust status of the certificate chain. -Validating the trust of the certificate chain may be complicated, and this field should only be populated by tools that actively check the status. - -type: boolean - -example: true - --- - -*`threat.enrichments.indicator.file.code_signature.valid`*:: -+ --- -Boolean to capture if the digital signature is verified against the binary content. -Leave unpopulated if a certificate was unchecked. - -type: boolean - -example: true - --- - -*`threat.enrichments.indicator.file.created`*:: -+ --- -File creation time. -Note that not all filesystems store the creation time. - -type: date - --- - -*`threat.enrichments.indicator.file.ctime`*:: -+ --- -Last time the file attributes or metadata changed. -Note that changes to the file content will update `mtime`. This implies `ctime` will be adjusted at the same time, since `mtime` is an attribute of the file. - -type: date - --- - -*`threat.enrichments.indicator.file.device`*:: -+ --- -Device that is the source of the file. - -type: keyword - -example: sda - --- - -*`threat.enrichments.indicator.file.directory`*:: -+ --- -Directory where the file is located. It should include the drive letter, when appropriate. - -type: keyword - -example: /home/alice - --- - -*`threat.enrichments.indicator.file.drive_letter`*:: -+ --- -Drive letter where the file is located. This field is only relevant on Windows. -The value should be uppercase, and not include the colon. - -type: keyword - -example: C - --- - -*`threat.enrichments.indicator.file.elf.architecture`*:: -+ --- -Machine architecture of the ELF file. - -type: keyword - -example: x86-64 - --- - -*`threat.enrichments.indicator.file.elf.byte_order`*:: -+ --- -Byte sequence of ELF file. - -type: keyword - -example: Little Endian - --- - -*`threat.enrichments.indicator.file.elf.cpu_type`*:: -+ --- -CPU type of the ELF file. - -type: keyword - -example: Intel - --- - -*`threat.enrichments.indicator.file.elf.creation_date`*:: -+ --- -Extracted when possible from the file's metadata. Indicates when it was built or compiled. It can also be faked by malware creators. - -type: date - --- - -*`threat.enrichments.indicator.file.elf.exports`*:: -+ --- -List of exported element names and types. - -type: flattened - --- - -*`threat.enrichments.indicator.file.elf.header.abi_version`*:: -+ --- -Version of the ELF Application Binary Interface (ABI). - -type: keyword - --- - -*`threat.enrichments.indicator.file.elf.header.class`*:: -+ --- -Header class of the ELF file. - -type: keyword - --- - -*`threat.enrichments.indicator.file.elf.header.data`*:: -+ --- -Data table of the ELF header. - -type: keyword - --- - -*`threat.enrichments.indicator.file.elf.header.entrypoint`*:: -+ --- -Header entrypoint of the ELF file. - -type: long - -format: string - --- - -*`threat.enrichments.indicator.file.elf.header.object_version`*:: -+ --- -"0x1" for original ELF files. - -type: keyword - --- - -*`threat.enrichments.indicator.file.elf.header.os_abi`*:: -+ --- -Application Binary Interface (ABI) of the Linux OS. - -type: keyword - --- - -*`threat.enrichments.indicator.file.elf.header.type`*:: -+ --- -Header type of the ELF file. - -type: keyword - --- - -*`threat.enrichments.indicator.file.elf.header.version`*:: -+ --- -Version of the ELF header. - -type: keyword - --- - -*`threat.enrichments.indicator.file.elf.imports`*:: -+ --- -List of imported element names and types. - -type: flattened - --- - -*`threat.enrichments.indicator.file.elf.sections`*:: -+ --- -An array containing an object for each section of the ELF file. -The keys that should be present in these objects are defined by sub-fields underneath `elf.sections.*`. - -type: nested - --- - -*`threat.enrichments.indicator.file.elf.sections.chi2`*:: -+ --- -Chi-square probability distribution of the section. - -type: long - -format: number - --- - -*`threat.enrichments.indicator.file.elf.sections.entropy`*:: -+ --- -Shannon entropy calculation from the section. - -type: long - -format: number - --- - -*`threat.enrichments.indicator.file.elf.sections.flags`*:: -+ --- -ELF Section List flags. - -type: keyword - --- - -*`threat.enrichments.indicator.file.elf.sections.name`*:: -+ --- -ELF Section List name. - -type: keyword - --- - -*`threat.enrichments.indicator.file.elf.sections.physical_offset`*:: -+ --- -ELF Section List offset. - -type: keyword - --- - -*`threat.enrichments.indicator.file.elf.sections.physical_size`*:: -+ --- -ELF Section List physical size. - -type: long - -format: bytes - --- - -*`threat.enrichments.indicator.file.elf.sections.type`*:: -+ --- -ELF Section List type. - -type: keyword - --- - -*`threat.enrichments.indicator.file.elf.sections.virtual_address`*:: -+ --- -ELF Section List virtual address. - -type: long - -format: string - --- - -*`threat.enrichments.indicator.file.elf.sections.virtual_size`*:: -+ --- -ELF Section List virtual size. - -type: long - -format: string - --- - -*`threat.enrichments.indicator.file.elf.segments`*:: -+ --- -An array containing an object for each segment of the ELF file. -The keys that should be present in these objects are defined by sub-fields underneath `elf.segments.*`. - -type: nested - --- - -*`threat.enrichments.indicator.file.elf.segments.sections`*:: -+ --- -ELF object segment sections. - -type: keyword - --- - -*`threat.enrichments.indicator.file.elf.segments.type`*:: -+ --- -ELF object segment type. - -type: keyword - --- - -*`threat.enrichments.indicator.file.elf.shared_libraries`*:: -+ --- -List of shared libraries used by this ELF object. - -type: keyword - --- - -*`threat.enrichments.indicator.file.elf.telfhash`*:: -+ --- -telfhash symbol hash for ELF file. - -type: keyword - --- - -*`threat.enrichments.indicator.file.extension`*:: -+ --- -File extension, excluding the leading dot. -Note that when the file name has multiple extensions (example.tar.gz), only the last one should be captured ("gz", not "tar.gz"). - -type: keyword - -example: png - --- - -*`threat.enrichments.indicator.file.fork_name`*:: -+ --- -A fork is additional data associated with a filesystem object. -On Linux, a resource fork is used to store additional data with a filesystem object. A file always has at least one fork for the data portion, and additional forks may exist. -On NTFS, this is analogous to an Alternate Data Stream (ADS), and the default data stream for a file is just called $DATA. Zone.Identifier is commonly used by Windows to track contents downloaded from the Internet. An ADS is typically of the form: `C:\path\to\filename.extension:some_fork_name`, and `some_fork_name` is the value that should populate `fork_name`. `filename.extension` should populate `file.name`, and `extension` should populate `file.extension`. The full path, `file.path`, will include the fork name. - -type: keyword - -example: Zone.Identifer - --- - -*`threat.enrichments.indicator.file.gid`*:: -+ --- -Primary group ID (GID) of the file. - -type: keyword - -example: 1001 - --- - -*`threat.enrichments.indicator.file.group`*:: -+ --- -Primary group name of the file. - -type: keyword - -example: alice - --- - -*`threat.enrichments.indicator.file.hash.md5`*:: -+ --- -MD5 hash. - -type: keyword - --- - -*`threat.enrichments.indicator.file.hash.sha1`*:: -+ --- -SHA1 hash. - -type: keyword - --- - -*`threat.enrichments.indicator.file.hash.sha256`*:: -+ --- -SHA256 hash. - -type: keyword - --- - -*`threat.enrichments.indicator.file.hash.sha512`*:: -+ --- -SHA512 hash. - -type: keyword - --- - -*`threat.enrichments.indicator.file.hash.ssdeep`*:: -+ --- -SSDEEP hash. - -type: keyword - --- - -*`threat.enrichments.indicator.file.inode`*:: -+ --- -Inode representing the file in the filesystem. - -type: keyword - -example: 256383 - --- - -*`threat.enrichments.indicator.file.mime_type`*:: -+ --- -MIME type should identify the format of the file or stream of bytes using https://www.iana.org/assignments/media-types/media-types.xhtml[IANA official types], where possible. When more than one type is applicable, the most specific type should be used. - -type: keyword - --- - -*`threat.enrichments.indicator.file.mode`*:: -+ --- -Mode of the file in octal representation. - -type: keyword - -example: 0640 - --- - -*`threat.enrichments.indicator.file.mtime`*:: -+ --- -Last time the file content was modified. - -type: date - --- - -*`threat.enrichments.indicator.file.name`*:: -+ --- -Name of the file including the extension, without the directory. - -type: keyword - -example: example.png - --- - -*`threat.enrichments.indicator.file.owner`*:: -+ --- -File owner's username. - -type: keyword - -example: alice - --- - -*`threat.enrichments.indicator.file.path`*:: -+ --- -Full path to the file, including the file name. It should include the drive letter, when appropriate. - -type: keyword - -example: /home/alice/example.png - --- - -*`threat.enrichments.indicator.file.path.text`*:: -+ --- -type: match_only_text - --- - -*`threat.enrichments.indicator.file.pe.architecture`*:: -+ --- -CPU architecture target for the file. - -type: keyword - -example: x64 - --- - -*`threat.enrichments.indicator.file.pe.company`*:: -+ --- -Internal company name of the file, provided at compile-time. - -type: keyword - -example: Microsoft Corporation - --- - -*`threat.enrichments.indicator.file.pe.description`*:: -+ --- -Internal description of the file, provided at compile-time. - -type: keyword - -example: Paint - --- - -*`threat.enrichments.indicator.file.pe.file_version`*:: -+ --- -Internal version of the file, provided at compile-time. - -type: keyword - -example: 6.3.9600.17415 - --- - -*`threat.enrichments.indicator.file.pe.imphash`*:: -+ --- -A hash of the imports in a PE file. An imphash -- or import hash -- can be used to fingerprint binaries even after recompilation or other code-level transformations have occurred, which would change more traditional hash values. -Learn more at https://www.fireeye.com/blog/threat-research/2014/01/tracking-malware-import-hashing.html. - -type: keyword - -example: 0c6803c4e922103c4dca5963aad36ddf - --- - -*`threat.enrichments.indicator.file.pe.original_file_name`*:: -+ --- -Internal name of the file, provided at compile-time. - -type: keyword - -example: MSPAINT.EXE - --- - -*`threat.enrichments.indicator.file.pe.product`*:: -+ --- -Internal product name of the file, provided at compile-time. - -type: keyword - -example: Microsoft® Windows® Operating System - --- - -*`threat.enrichments.indicator.file.size`*:: -+ --- -File size in bytes. -Only relevant when `file.type` is "file". - -type: long - -example: 16384 - --- - -*`threat.enrichments.indicator.file.target_path`*:: -+ --- -Target path for symlinks. - -type: keyword - --- - -*`threat.enrichments.indicator.file.target_path.text`*:: -+ --- -type: match_only_text - --- - -*`threat.enrichments.indicator.file.type`*:: -+ --- -File type (file, dir, or symlink). - -type: keyword - -example: file - --- - -*`threat.enrichments.indicator.file.uid`*:: -+ --- -The user ID (UID) or security identifier (SID) of the file owner. - -type: keyword - -example: 1001 - --- - -*`threat.enrichments.indicator.file.x509.alternative_names`*:: -+ --- -List of subject alternative names (SAN). Name types vary by certificate authority and certificate type but commonly contain IP addresses, DNS names (and wildcards), and email addresses. - -type: keyword - -example: *.elastic.co - --- - -*`threat.enrichments.indicator.file.x509.issuer.common_name`*:: -+ --- -List of common name (CN) of issuing certificate authority. - -type: keyword - -example: Example SHA2 High Assurance Server CA - --- - -*`threat.enrichments.indicator.file.x509.issuer.country`*:: -+ --- -List of country (C) codes - -type: keyword - -example: US - --- - -*`threat.enrichments.indicator.file.x509.issuer.distinguished_name`*:: -+ --- -Distinguished name (DN) of issuing certificate authority. - -type: keyword - -example: C=US, O=Example Inc, OU=www.example.com, CN=Example SHA2 High Assurance Server CA - --- - -*`threat.enrichments.indicator.file.x509.issuer.locality`*:: -+ --- -List of locality names (L) - -type: keyword - -example: Mountain View - --- - -*`threat.enrichments.indicator.file.x509.issuer.organization`*:: -+ --- -List of organizations (O) of issuing certificate authority. - -type: keyword - -example: Example Inc - --- - -*`threat.enrichments.indicator.file.x509.issuer.organizational_unit`*:: -+ --- -List of organizational units (OU) of issuing certificate authority. - -type: keyword - -example: www.example.com - --- - -*`threat.enrichments.indicator.file.x509.issuer.state_or_province`*:: -+ --- -List of state or province names (ST, S, or P) - -type: keyword - -example: California - --- - -*`threat.enrichments.indicator.file.x509.not_after`*:: -+ --- -Time at which the certificate is no longer considered valid. - -type: date - -example: 2020-07-16 03:15:39+00:00 - --- - -*`threat.enrichments.indicator.file.x509.not_before`*:: -+ --- -Time at which the certificate is first considered valid. - -type: date - -example: 2019-08-16 01:40:25+00:00 - --- - -*`threat.enrichments.indicator.file.x509.public_key_algorithm`*:: -+ --- -Algorithm used to generate the public key. - -type: keyword - -example: RSA - --- - -*`threat.enrichments.indicator.file.x509.public_key_curve`*:: -+ --- -The curve used by the elliptic curve public key algorithm. This is algorithm specific. - -type: keyword - -example: nistp521 - --- - -*`threat.enrichments.indicator.file.x509.public_key_exponent`*:: -+ --- -Exponent used to derive the public key. This is algorithm specific. - -type: long - -example: 65537 - -Field is not indexed. - --- - -*`threat.enrichments.indicator.file.x509.public_key_size`*:: -+ --- -The size of the public key space in bits. - -type: long - -example: 2048 - --- - -*`threat.enrichments.indicator.file.x509.serial_number`*:: -+ --- -Unique serial number issued by the certificate authority. For consistency, if this value is alphanumeric, it should be formatted without colons and uppercase characters. - -type: keyword - -example: 55FBB9C7DEBF09809D12CCAA - --- - -*`threat.enrichments.indicator.file.x509.signature_algorithm`*:: -+ --- -Identifier for certificate signature algorithm. We recommend using names found in Go Lang Crypto library. See https://github.com/golang/go/blob/go1.14/src/crypto/x509/x509.go#L337-L353. - -type: keyword - -example: SHA256-RSA - --- - -*`threat.enrichments.indicator.file.x509.subject.common_name`*:: -+ --- -List of common names (CN) of subject. - -type: keyword - -example: shared.global.example.net - --- - -*`threat.enrichments.indicator.file.x509.subject.country`*:: -+ --- -List of country (C) code - -type: keyword - -example: US - --- - -*`threat.enrichments.indicator.file.x509.subject.distinguished_name`*:: -+ --- -Distinguished name (DN) of the certificate subject entity. - -type: keyword - -example: C=US, ST=California, L=San Francisco, O=Example, Inc., CN=shared.global.example.net - --- - -*`threat.enrichments.indicator.file.x509.subject.locality`*:: -+ --- -List of locality names (L) - -type: keyword - -example: San Francisco - --- - -*`threat.enrichments.indicator.file.x509.subject.organization`*:: -+ --- -List of organizations (O) of subject. - -type: keyword - -example: Example, Inc. - --- - -*`threat.enrichments.indicator.file.x509.subject.organizational_unit`*:: -+ --- -List of organizational units (OU) of subject. - -type: keyword - --- - -*`threat.enrichments.indicator.file.x509.subject.state_or_province`*:: -+ --- -List of state or province names (ST, S, or P) - -type: keyword - -example: California - --- - -*`threat.enrichments.indicator.file.x509.version_number`*:: -+ --- -Version of x509 format. - -type: keyword - -example: 3 - --- - -*`threat.enrichments.indicator.first_seen`*:: -+ --- -The date and time when intelligence source first reported sighting this indicator. - -type: date - -example: 2020-11-05T17:25:47.000Z - --- - -*`threat.enrichments.indicator.geo.city_name`*:: -+ --- -City name. - -type: keyword - -example: Montreal - --- - -*`threat.enrichments.indicator.geo.continent_code`*:: -+ --- -Two-letter code representing continent's name. - -type: keyword - -example: NA - --- - -*`threat.enrichments.indicator.geo.continent_name`*:: -+ --- -Name of the continent. - -type: keyword - -example: North America - --- - -*`threat.enrichments.indicator.geo.country_iso_code`*:: -+ --- -Country ISO code. - -type: keyword - -example: CA - --- - -*`threat.enrichments.indicator.geo.country_name`*:: -+ --- -Country name. - -type: keyword - -example: Canada - --- - -*`threat.enrichments.indicator.geo.location`*:: -+ --- -Longitude and latitude. - -type: geo_point - -example: { "lon": -73.614830, "lat": 45.505918 } - --- - -*`threat.enrichments.indicator.geo.name`*:: -+ --- -User-defined description of a location, at the level of granularity they care about. -Could be the name of their data centers, the floor number, if this describes a local physical entity, city names. -Not typically used in automated geolocation. - -type: keyword - -example: boston-dc - --- - -*`threat.enrichments.indicator.geo.postal_code`*:: -+ --- -Postal code associated with the location. -Values appropriate for this field may also be known as a postcode or ZIP code and will vary widely from country to country. - -type: keyword - -example: 94040 - --- - -*`threat.enrichments.indicator.geo.region_iso_code`*:: -+ --- -Region ISO code. - -type: keyword - -example: CA-QC - --- - -*`threat.enrichments.indicator.geo.region_name`*:: -+ --- -Region name. - -type: keyword - -example: Quebec - --- - -*`threat.enrichments.indicator.geo.timezone`*:: -+ --- -The time zone of the location, such as IANA time zone name. - -type: keyword - -example: America/Argentina/Buenos_Aires - --- - -*`threat.enrichments.indicator.ip`*:: -+ --- -Identifies a threat indicator as an IP address (irrespective of direction). - -type: ip - -example: 1.2.3.4 - --- - -*`threat.enrichments.indicator.last_seen`*:: -+ --- -The date and time when intelligence source last reported sighting this indicator. - -type: date - -example: 2020-11-05T17:25:47.000Z - --- - -*`threat.enrichments.indicator.marking.tlp`*:: -+ --- -Traffic Light Protocol sharing markings. Recommended values are: - * WHITE - * GREEN - * AMBER - * RED - -type: keyword - -example: White - --- - -*`threat.enrichments.indicator.modified_at`*:: -+ --- -The date and time when intelligence source last modified information for this indicator. - -type: date - -example: 2020-11-05T17:25:47.000Z - --- - -*`threat.enrichments.indicator.port`*:: -+ --- -Identifies a threat indicator as a port number (irrespective of direction). - -type: long - -example: 443 - --- - -*`threat.enrichments.indicator.provider`*:: -+ --- -The name of the indicator's provider. - -type: keyword - -example: lrz_urlhaus - --- - -*`threat.enrichments.indicator.reference`*:: -+ --- -Reference URL linking to additional information about this indicator. - -type: keyword - -example: https://system.example.com/indicator/0001234 - --- - -*`threat.enrichments.indicator.registry.data.bytes`*:: -+ --- -Original bytes written with base64 encoding. -For Windows registry operations, such as SetValueEx and RegQueryValueEx, this corresponds to the data pointed by `lp_data`. This is optional but provides better recoverability and should be populated for REG_BINARY encoded values. - -type: keyword - -example: ZQBuAC0AVQBTAAAAZQBuAAAAAAA= - --- - -*`threat.enrichments.indicator.registry.data.strings`*:: -+ --- -Content when writing string types. -Populated as an array when writing string data to the registry. For single string registry types (REG_SZ, REG_EXPAND_SZ), this should be an array with one string. For sequences of string with REG_MULTI_SZ, this array will be variable length. For numeric data, such as REG_DWORD and REG_QWORD, this should be populated with the decimal representation (e.g `"1"`). - -type: wildcard - -example: ["C:\rta\red_ttp\bin\myapp.exe"] - --- - -*`threat.enrichments.indicator.registry.data.type`*:: -+ --- -Standard registry type for encoding contents - -type: keyword - -example: REG_SZ - --- - -*`threat.enrichments.indicator.registry.hive`*:: -+ --- -Abbreviated name for the hive. - -type: keyword - -example: HKLM - --- - -*`threat.enrichments.indicator.registry.key`*:: -+ --- -Hive-relative path of keys. - -type: keyword - -example: SOFTWARE\Microsoft\Windows NT\CurrentVersion\Image File Execution Options\winword.exe - --- - -*`threat.enrichments.indicator.registry.path`*:: -+ --- -Full path, including hive, key and value - -type: keyword - -example: HKLM\SOFTWARE\Microsoft\Windows NT\CurrentVersion\Image File Execution Options\winword.exe\Debugger - --- - -*`threat.enrichments.indicator.registry.value`*:: -+ --- -Name of the value written. - -type: keyword - -example: Debugger - --- - -*`threat.enrichments.indicator.scanner_stats`*:: -+ --- -Count of AV/EDR vendors that successfully detected malicious file or URL. - -type: long - -example: 4 - --- - -*`threat.enrichments.indicator.sightings`*:: -+ --- -Number of times this indicator was observed conducting threat activity. - -type: long - -example: 20 - --- - -*`threat.enrichments.indicator.type`*:: -+ --- -Type of indicator as represented by Cyber Observable in STIX 2.0. Recommended values: - * autonomous-system - * artifact - * directory - * domain-name - * email-addr - * file - * ipv4-addr - * ipv6-addr - * mac-addr - * mutex - * port - * process - * software - * url - * user-account - * windows-registry-key - * x509-certificate - -type: keyword - -example: ipv4-addr - --- - -*`threat.enrichments.indicator.url.domain`*:: -+ --- -Domain of the url, such as "www.elastic.co". -In some cases a URL may refer to an IP and/or port directly, without a domain name. In this case, the IP address would go to the `domain` field. -If the URL contains a literal IPv6 address enclosed by `[` and `]` (IETF RFC 2732), the `[` and `]` characters should also be captured in the `domain` field. - -type: keyword - -example: www.elastic.co - --- - -*`threat.enrichments.indicator.url.extension`*:: -+ --- -The field contains the file extension from the original request url, excluding the leading dot. -The file extension is only set if it exists, as not every url has a file extension. -The leading period must not be included. For example, the value must be "png", not ".png". -Note that when the file name has multiple extensions (example.tar.gz), only the last one should be captured ("gz", not "tar.gz"). - -type: keyword - -example: png - --- - -*`threat.enrichments.indicator.url.fragment`*:: -+ --- -Portion of the url after the `#`, such as "top". -The `#` is not part of the fragment. - -type: keyword - --- - -*`threat.enrichments.indicator.url.full`*:: -+ --- -If full URLs are important to your use case, they should be stored in `url.full`, whether this field is reconstructed or present in the event source. - -type: wildcard - -example: https://www.elastic.co:443/search?q=elasticsearch#top - --- - -*`threat.enrichments.indicator.url.full.text`*:: -+ --- -type: match_only_text - --- - -*`threat.enrichments.indicator.url.original`*:: -+ --- -Unmodified original url as seen in the event source. -Note that in network monitoring, the observed URL may be a full URL, whereas in access logs, the URL is often just represented as a path. -This field is meant to represent the URL as it was observed, complete or not. - -type: wildcard - -example: https://www.elastic.co:443/search?q=elasticsearch#top or /search?q=elasticsearch - --- - -*`threat.enrichments.indicator.url.original.text`*:: -+ --- -type: match_only_text - --- - -*`threat.enrichments.indicator.url.password`*:: -+ --- -Password of the request. - -type: keyword - --- - -*`threat.enrichments.indicator.url.path`*:: -+ --- -Path of the request, such as "/search". - -type: wildcard - --- - -*`threat.enrichments.indicator.url.port`*:: -+ --- -Port of the request, such as 443. - -type: long - -example: 443 - -format: string - --- - -*`threat.enrichments.indicator.url.query`*:: -+ --- -The query field describes the query string of the request, such as "q=elasticsearch". -The `?` is excluded from the query string. If a URL contains no `?`, there is no query field. If there is a `?` but no query, the query field exists with an empty string. The `exists` query can be used to differentiate between the two cases. - -type: keyword - --- - -*`threat.enrichments.indicator.url.registered_domain`*:: -+ --- -The highest registered url domain, stripped of the subdomain. -For example, the registered domain for "foo.example.com" is "example.com". -This value can be determined precisely with a list like the public suffix list (http://publicsuffix.org). Trying to approximate this by simply taking the last two labels will not work well for TLDs such as "co.uk". - -type: keyword - -example: example.com - --- - -*`threat.enrichments.indicator.url.scheme`*:: -+ --- -Scheme of the request, such as "https". -Note: The `:` is not part of the scheme. - -type: keyword - -example: https - --- - -*`threat.enrichments.indicator.url.subdomain`*:: -+ --- -The subdomain portion of a fully qualified domain name includes all of the names except the host name under the registered_domain. In a partially qualified domain, or if the the qualification level of the full name cannot be determined, subdomain contains all of the names below the registered domain. -For example the subdomain portion of "www.east.mydomain.co.uk" is "east". If the domain has multiple levels of subdomain, such as "sub2.sub1.example.com", the subdomain field should contain "sub2.sub1", with no trailing period. - -type: keyword - -example: east - --- - -*`threat.enrichments.indicator.url.top_level_domain`*:: -+ --- -The effective top level domain (eTLD), also known as the domain suffix, is the last part of the domain name. For example, the top level domain for example.com is "com". -This value can be determined precisely with a list like the public suffix list (http://publicsuffix.org). Trying to approximate this by simply taking the last label will not work well for effective TLDs such as "co.uk". - -type: keyword - -example: co.uk - --- - -*`threat.enrichments.indicator.url.username`*:: -+ --- -Username of the request. - -type: keyword - --- - -*`threat.enrichments.indicator.x509.alternative_names`*:: -+ --- -List of subject alternative names (SAN). Name types vary by certificate authority and certificate type but commonly contain IP addresses, DNS names (and wildcards), and email addresses. - -type: keyword - -example: *.elastic.co - --- - -*`threat.enrichments.indicator.x509.issuer.common_name`*:: -+ --- -List of common name (CN) of issuing certificate authority. - -type: keyword - -example: Example SHA2 High Assurance Server CA - --- - -*`threat.enrichments.indicator.x509.issuer.country`*:: -+ --- -List of country (C) codes - -type: keyword - -example: US - --- - -*`threat.enrichments.indicator.x509.issuer.distinguished_name`*:: -+ --- -Distinguished name (DN) of issuing certificate authority. - -type: keyword - -example: C=US, O=Example Inc, OU=www.example.com, CN=Example SHA2 High Assurance Server CA - --- - -*`threat.enrichments.indicator.x509.issuer.locality`*:: -+ --- -List of locality names (L) - -type: keyword - -example: Mountain View - --- - -*`threat.enrichments.indicator.x509.issuer.organization`*:: -+ --- -List of organizations (O) of issuing certificate authority. - -type: keyword - -example: Example Inc - --- - -*`threat.enrichments.indicator.x509.issuer.organizational_unit`*:: -+ --- -List of organizational units (OU) of issuing certificate authority. - -type: keyword - -example: www.example.com - --- - -*`threat.enrichments.indicator.x509.issuer.state_or_province`*:: -+ --- -List of state or province names (ST, S, or P) - -type: keyword - -example: California - --- - -*`threat.enrichments.indicator.x509.not_after`*:: -+ --- -Time at which the certificate is no longer considered valid. - -type: date - -example: 2020-07-16 03:15:39+00:00 - --- - -*`threat.enrichments.indicator.x509.not_before`*:: -+ --- -Time at which the certificate is first considered valid. - -type: date - -example: 2019-08-16 01:40:25+00:00 - --- - -*`threat.enrichments.indicator.x509.public_key_algorithm`*:: -+ --- -Algorithm used to generate the public key. - -type: keyword - -example: RSA - --- - -*`threat.enrichments.indicator.x509.public_key_curve`*:: -+ --- -The curve used by the elliptic curve public key algorithm. This is algorithm specific. - -type: keyword - -example: nistp521 - --- - -*`threat.enrichments.indicator.x509.public_key_exponent`*:: -+ --- -Exponent used to derive the public key. This is algorithm specific. - -type: long - -example: 65537 - -Field is not indexed. - --- - -*`threat.enrichments.indicator.x509.public_key_size`*:: -+ --- -The size of the public key space in bits. - -type: long - -example: 2048 - --- - -*`threat.enrichments.indicator.x509.serial_number`*:: -+ --- -Unique serial number issued by the certificate authority. For consistency, if this value is alphanumeric, it should be formatted without colons and uppercase characters. - -type: keyword - -example: 55FBB9C7DEBF09809D12CCAA - --- - -*`threat.enrichments.indicator.x509.signature_algorithm`*:: -+ --- -Identifier for certificate signature algorithm. We recommend using names found in Go Lang Crypto library. See https://github.com/golang/go/blob/go1.14/src/crypto/x509/x509.go#L337-L353. - -type: keyword - -example: SHA256-RSA - --- - -*`threat.enrichments.indicator.x509.subject.common_name`*:: -+ --- -List of common names (CN) of subject. - -type: keyword - -example: shared.global.example.net - --- - -*`threat.enrichments.indicator.x509.subject.country`*:: -+ --- -List of country (C) code - -type: keyword - -example: US - --- - -*`threat.enrichments.indicator.x509.subject.distinguished_name`*:: -+ --- -Distinguished name (DN) of the certificate subject entity. - -type: keyword - -example: C=US, ST=California, L=San Francisco, O=Example, Inc., CN=shared.global.example.net - --- - -*`threat.enrichments.indicator.x509.subject.locality`*:: -+ --- -List of locality names (L) - -type: keyword - -example: San Francisco - --- - -*`threat.enrichments.indicator.x509.subject.organization`*:: -+ --- -List of organizations (O) of subject. - -type: keyword - -example: Example, Inc. - --- - -*`threat.enrichments.indicator.x509.subject.organizational_unit`*:: -+ --- -List of organizational units (OU) of subject. - -type: keyword - --- - -*`threat.enrichments.indicator.x509.subject.state_or_province`*:: -+ --- -List of state or province names (ST, S, or P) - -type: keyword - -example: California - --- - -*`threat.enrichments.indicator.x509.version_number`*:: -+ --- -Version of x509 format. - -type: keyword - -example: 3 - --- - -*`threat.enrichments.matched.atomic`*:: -+ --- -Identifies the atomic indicator value that matched a local environment endpoint or network event. - -type: keyword - -example: bad-domain.com - --- - -*`threat.enrichments.matched.field`*:: -+ --- -Identifies the field of the atomic indicator that matched a local environment endpoint or network event. - -type: keyword - -example: file.hash.sha256 - --- - -*`threat.enrichments.matched.id`*:: -+ --- -Identifies the _id of the indicator document enriching the event. - -type: keyword - -example: ff93aee5-86a1-4a61-b0e6-0cdc313d01b5 - --- - -*`threat.enrichments.matched.index`*:: -+ --- -Identifies the _index of the indicator document enriching the event. - -type: keyword - -example: filebeat-8.0.0-2021.05.23-000011 - --- - -*`threat.enrichments.matched.type`*:: -+ --- -Identifies the type of match that caused the event to be enriched with the given indicator - -type: keyword - -example: indicator_match_rule - --- - -*`threat.framework`*:: -+ --- -Name of the threat framework used to further categorize and classify the tactic and technique of the reported threat. Framework classification can be provided by detecting systems, evaluated at ingest time, or retrospectively tagged to events. - -type: keyword - -example: MITRE ATT&CK - --- - -*`threat.group.alias`*:: -+ --- -The alias(es) of the group for a set of related intrusion activity that are tracked by a common name in the security community. -While not required, you can use a MITRE ATT&CK® group alias(es). - -type: keyword - -example: [ "Magecart Group 6" ] - --- - -*`threat.group.id`*:: -+ --- -The id of the group for a set of related intrusion activity that are tracked by a common name in the security community. -While not required, you can use a MITRE ATT&CK® group id. - -type: keyword - -example: G0037 - --- - -*`threat.group.name`*:: -+ --- -The name of the group for a set of related intrusion activity that are tracked by a common name in the security community. -While not required, you can use a MITRE ATT&CK® group name. - -type: keyword - -example: FIN6 - --- - -*`threat.group.reference`*:: -+ --- -The reference URL of the group for a set of related intrusion activity that are tracked by a common name in the security community. -While not required, you can use a MITRE ATT&CK® group reference URL. - -type: keyword - -example: https://attack.mitre.org/groups/G0037/ - --- - -*`threat.indicator.as.number`*:: -+ --- -Unique number allocated to the autonomous system. The autonomous system number (ASN) uniquely identifies each network on the Internet. - -type: long - -example: 15169 - --- - -*`threat.indicator.as.organization.name`*:: -+ --- -Organization name. - -type: keyword - -example: Google LLC - --- - -*`threat.indicator.as.organization.name.text`*:: -+ --- -type: match_only_text - --- - -*`threat.indicator.confidence`*:: -+ --- -Identifies the vendor-neutral confidence rating using the None/Low/Medium/High scale defined in Appendix A of the STIX 2.1 framework. Vendor-specific confidence scales may be added as custom fields. -Expected values are: - * Not Specified - * None - * Low - * Medium - * High - -type: keyword - -example: Medium - --- - -*`threat.indicator.description`*:: -+ --- -Describes the type of action conducted by the threat. - -type: keyword - -example: IP x.x.x.x was observed delivering the Angler EK. - --- - -*`threat.indicator.email.address`*:: -+ --- -Identifies a threat indicator as an email address (irrespective of direction). - -type: keyword - -example: phish@example.com - --- - -*`threat.indicator.file.accessed`*:: -+ --- -Last time the file was accessed. -Note that not all filesystems keep track of access time. - -type: date - --- - -*`threat.indicator.file.attributes`*:: -+ --- -Array of file attributes. -Attributes names will vary by platform. Here's a non-exhaustive list of values that are expected in this field: archive, compressed, directory, encrypted, execute, hidden, read, readonly, system, write. - -type: keyword - -example: ["readonly", "system"] - --- - -*`threat.indicator.file.code_signature.digest_algorithm`*:: -+ --- -The hashing algorithm used to sign the process. -This value can distinguish signatures when a file is signed multiple times by the same signer but with a different digest algorithm. - -type: keyword - -example: sha256 - --- - -*`threat.indicator.file.code_signature.exists`*:: -+ --- -Boolean to capture if a signature is present. - -type: boolean - -example: true - --- - -*`threat.indicator.file.code_signature.signing_id`*:: -+ --- -The identifier used to sign the process. -This is used to identify the application manufactured by a software vendor. The field is relevant to Apple *OS only. - -type: keyword - -example: com.apple.xpc.proxy - --- - -*`threat.indicator.file.code_signature.status`*:: -+ --- -Additional information about the certificate status. -This is useful for logging cryptographic errors with the certificate validity or trust status. Leave unpopulated if the validity or trust of the certificate was unchecked. - -type: keyword - -example: ERROR_UNTRUSTED_ROOT - --- - -*`threat.indicator.file.code_signature.subject_name`*:: -+ --- -Subject name of the code signer - -type: keyword - -example: Microsoft Corporation - --- - -*`threat.indicator.file.code_signature.team_id`*:: -+ --- -The team identifier used to sign the process. -This is used to identify the team or vendor of a software product. The field is relevant to Apple *OS only. - -type: keyword - -example: EQHXZ8M8AV - --- - -*`threat.indicator.file.code_signature.timestamp`*:: -+ --- -Date and time when the code signature was generated and signed. - -type: date - -example: 2021-01-01T12:10:30Z - --- - -*`threat.indicator.file.code_signature.trusted`*:: -+ --- -Stores the trust status of the certificate chain. -Validating the trust of the certificate chain may be complicated, and this field should only be populated by tools that actively check the status. - -type: boolean - -example: true - --- - -*`threat.indicator.file.code_signature.valid`*:: -+ --- -Boolean to capture if the digital signature is verified against the binary content. -Leave unpopulated if a certificate was unchecked. - -type: boolean - -example: true - --- - -*`threat.indicator.file.created`*:: -+ --- -File creation time. -Note that not all filesystems store the creation time. - -type: date - --- - -*`threat.indicator.file.ctime`*:: -+ --- -Last time the file attributes or metadata changed. -Note that changes to the file content will update `mtime`. This implies `ctime` will be adjusted at the same time, since `mtime` is an attribute of the file. - -type: date - --- - -*`threat.indicator.file.device`*:: -+ --- -Device that is the source of the file. - -type: keyword - -example: sda - --- - -*`threat.indicator.file.directory`*:: -+ --- -Directory where the file is located. It should include the drive letter, when appropriate. - -type: keyword - -example: /home/alice - --- - -*`threat.indicator.file.drive_letter`*:: -+ --- -Drive letter where the file is located. This field is only relevant on Windows. -The value should be uppercase, and not include the colon. - -type: keyword - -example: C - --- - -*`threat.indicator.file.elf.architecture`*:: -+ --- -Machine architecture of the ELF file. - -type: keyword - -example: x86-64 - --- - -*`threat.indicator.file.elf.byte_order`*:: -+ --- -Byte sequence of ELF file. - -type: keyword - -example: Little Endian - --- - -*`threat.indicator.file.elf.cpu_type`*:: -+ --- -CPU type of the ELF file. - -type: keyword - -example: Intel - --- - -*`threat.indicator.file.elf.creation_date`*:: -+ --- -Extracted when possible from the file's metadata. Indicates when it was built or compiled. It can also be faked by malware creators. - -type: date - --- - -*`threat.indicator.file.elf.exports`*:: -+ --- -List of exported element names and types. - -type: flattened - --- - -*`threat.indicator.file.elf.header.abi_version`*:: -+ --- -Version of the ELF Application Binary Interface (ABI). - -type: keyword - --- - -*`threat.indicator.file.elf.header.class`*:: -+ --- -Header class of the ELF file. - -type: keyword - --- - -*`threat.indicator.file.elf.header.data`*:: -+ --- -Data table of the ELF header. - -type: keyword - --- - -*`threat.indicator.file.elf.header.entrypoint`*:: -+ --- -Header entrypoint of the ELF file. - -type: long - -format: string - --- - -*`threat.indicator.file.elf.header.object_version`*:: -+ --- -"0x1" for original ELF files. - -type: keyword - --- - -*`threat.indicator.file.elf.header.os_abi`*:: -+ --- -Application Binary Interface (ABI) of the Linux OS. - -type: keyword - --- - -*`threat.indicator.file.elf.header.type`*:: -+ --- -Header type of the ELF file. - -type: keyword - --- - -*`threat.indicator.file.elf.header.version`*:: -+ --- -Version of the ELF header. - -type: keyword - --- - -*`threat.indicator.file.elf.imports`*:: -+ --- -List of imported element names and types. - -type: flattened - --- - -*`threat.indicator.file.elf.sections`*:: -+ --- -An array containing an object for each section of the ELF file. -The keys that should be present in these objects are defined by sub-fields underneath `elf.sections.*`. - -type: nested - --- - -*`threat.indicator.file.elf.sections.chi2`*:: -+ --- -Chi-square probability distribution of the section. - -type: long - -format: number - --- - -*`threat.indicator.file.elf.sections.entropy`*:: -+ --- -Shannon entropy calculation from the section. - -type: long - -format: number - --- - -*`threat.indicator.file.elf.sections.flags`*:: -+ --- -ELF Section List flags. - -type: keyword - --- - -*`threat.indicator.file.elf.sections.name`*:: -+ --- -ELF Section List name. - -type: keyword - --- - -*`threat.indicator.file.elf.sections.physical_offset`*:: -+ --- -ELF Section List offset. - -type: keyword - --- - -*`threat.indicator.file.elf.sections.physical_size`*:: -+ --- -ELF Section List physical size. - -type: long - -format: bytes - --- - -*`threat.indicator.file.elf.sections.type`*:: -+ --- -ELF Section List type. - -type: keyword - --- - -*`threat.indicator.file.elf.sections.virtual_address`*:: -+ --- -ELF Section List virtual address. - -type: long - -format: string - --- - -*`threat.indicator.file.elf.sections.virtual_size`*:: -+ --- -ELF Section List virtual size. - -type: long - -format: string - --- - -*`threat.indicator.file.elf.segments`*:: -+ --- -An array containing an object for each segment of the ELF file. -The keys that should be present in these objects are defined by sub-fields underneath `elf.segments.*`. - -type: nested - --- - -*`threat.indicator.file.elf.segments.sections`*:: -+ --- -ELF object segment sections. - -type: keyword - --- - -*`threat.indicator.file.elf.segments.type`*:: -+ --- -ELF object segment type. - -type: keyword - --- - -*`threat.indicator.file.elf.shared_libraries`*:: -+ --- -List of shared libraries used by this ELF object. - -type: keyword - --- - -*`threat.indicator.file.elf.telfhash`*:: -+ --- -telfhash symbol hash for ELF file. - -type: keyword - --- - -*`threat.indicator.file.extension`*:: -+ --- -File extension, excluding the leading dot. -Note that when the file name has multiple extensions (example.tar.gz), only the last one should be captured ("gz", not "tar.gz"). - -type: keyword - -example: png - --- - -*`threat.indicator.file.fork_name`*:: -+ --- -A fork is additional data associated with a filesystem object. -On Linux, a resource fork is used to store additional data with a filesystem object. A file always has at least one fork for the data portion, and additional forks may exist. -On NTFS, this is analogous to an Alternate Data Stream (ADS), and the default data stream for a file is just called $DATA. Zone.Identifier is commonly used by Windows to track contents downloaded from the Internet. An ADS is typically of the form: `C:\path\to\filename.extension:some_fork_name`, and `some_fork_name` is the value that should populate `fork_name`. `filename.extension` should populate `file.name`, and `extension` should populate `file.extension`. The full path, `file.path`, will include the fork name. - -type: keyword - -example: Zone.Identifer - --- - -*`threat.indicator.file.gid`*:: -+ --- -Primary group ID (GID) of the file. - -type: keyword - -example: 1001 - --- - -*`threat.indicator.file.group`*:: -+ --- -Primary group name of the file. - -type: keyword - -example: alice - --- - -*`threat.indicator.file.hash.md5`*:: -+ --- -MD5 hash. - -type: keyword - --- - -*`threat.indicator.file.hash.sha1`*:: -+ --- -SHA1 hash. - -type: keyword - --- - -*`threat.indicator.file.hash.sha256`*:: -+ --- -SHA256 hash. - -type: keyword - --- - -*`threat.indicator.file.hash.sha512`*:: -+ --- -SHA512 hash. - -type: keyword - --- - -*`threat.indicator.file.hash.ssdeep`*:: -+ --- -SSDEEP hash. - -type: keyword - --- - -*`threat.indicator.file.inode`*:: -+ --- -Inode representing the file in the filesystem. - -type: keyword - -example: 256383 - --- - -*`threat.indicator.file.mime_type`*:: -+ --- -MIME type should identify the format of the file or stream of bytes using https://www.iana.org/assignments/media-types/media-types.xhtml[IANA official types], where possible. When more than one type is applicable, the most specific type should be used. - -type: keyword - --- - -*`threat.indicator.file.mode`*:: -+ --- -Mode of the file in octal representation. - -type: keyword - -example: 0640 - --- - -*`threat.indicator.file.mtime`*:: -+ --- -Last time the file content was modified. - -type: date - --- - -*`threat.indicator.file.name`*:: -+ --- -Name of the file including the extension, without the directory. - -type: keyword - -example: example.png - --- - -*`threat.indicator.file.owner`*:: -+ --- -File owner's username. - -type: keyword - -example: alice - --- - -*`threat.indicator.file.path`*:: -+ --- -Full path to the file, including the file name. It should include the drive letter, when appropriate. - -type: keyword - -example: /home/alice/example.png - --- - -*`threat.indicator.file.path.text`*:: -+ --- -type: match_only_text - --- - -*`threat.indicator.file.pe.architecture`*:: -+ --- -CPU architecture target for the file. - -type: keyword - -example: x64 - --- - -*`threat.indicator.file.pe.company`*:: -+ --- -Internal company name of the file, provided at compile-time. - -type: keyword - -example: Microsoft Corporation - --- - -*`threat.indicator.file.pe.description`*:: -+ --- -Internal description of the file, provided at compile-time. - -type: keyword - -example: Paint - --- - -*`threat.indicator.file.pe.file_version`*:: -+ --- -Internal version of the file, provided at compile-time. - -type: keyword - -example: 6.3.9600.17415 - --- - -*`threat.indicator.file.pe.imphash`*:: -+ --- -A hash of the imports in a PE file. An imphash -- or import hash -- can be used to fingerprint binaries even after recompilation or other code-level transformations have occurred, which would change more traditional hash values. -Learn more at https://www.fireeye.com/blog/threat-research/2014/01/tracking-malware-import-hashing.html. - -type: keyword - -example: 0c6803c4e922103c4dca5963aad36ddf - --- - -*`threat.indicator.file.pe.original_file_name`*:: -+ --- -Internal name of the file, provided at compile-time. - -type: keyword - -example: MSPAINT.EXE - --- - -*`threat.indicator.file.pe.product`*:: -+ --- -Internal product name of the file, provided at compile-time. - -type: keyword - -example: Microsoft® Windows® Operating System - --- - -*`threat.indicator.file.size`*:: -+ --- -File size in bytes. -Only relevant when `file.type` is "file". - -type: long - -example: 16384 - --- - -*`threat.indicator.file.target_path`*:: -+ --- -Target path for symlinks. - -type: keyword - --- - -*`threat.indicator.file.target_path.text`*:: -+ --- -type: match_only_text - --- - -*`threat.indicator.file.type`*:: -+ --- -File type (file, dir, or symlink). - -type: keyword - -example: file - --- - -*`threat.indicator.file.uid`*:: -+ --- -The user ID (UID) or security identifier (SID) of the file owner. - -type: keyword - -example: 1001 - --- - -*`threat.indicator.file.x509.alternative_names`*:: -+ --- -List of subject alternative names (SAN). Name types vary by certificate authority and certificate type but commonly contain IP addresses, DNS names (and wildcards), and email addresses. - -type: keyword - -example: *.elastic.co - --- - -*`threat.indicator.file.x509.issuer.common_name`*:: -+ --- -List of common name (CN) of issuing certificate authority. - -type: keyword - -example: Example SHA2 High Assurance Server CA - --- - -*`threat.indicator.file.x509.issuer.country`*:: -+ --- -List of country (C) codes - -type: keyword - -example: US - --- - -*`threat.indicator.file.x509.issuer.distinguished_name`*:: -+ --- -Distinguished name (DN) of issuing certificate authority. - -type: keyword - -example: C=US, O=Example Inc, OU=www.example.com, CN=Example SHA2 High Assurance Server CA - --- - -*`threat.indicator.file.x509.issuer.locality`*:: -+ --- -List of locality names (L) - -type: keyword - -example: Mountain View - --- - -*`threat.indicator.file.x509.issuer.organization`*:: -+ --- -List of organizations (O) of issuing certificate authority. - -type: keyword - -example: Example Inc - --- - -*`threat.indicator.file.x509.issuer.organizational_unit`*:: -+ --- -List of organizational units (OU) of issuing certificate authority. - -type: keyword - -example: www.example.com - --- - -*`threat.indicator.file.x509.issuer.state_or_province`*:: -+ --- -List of state or province names (ST, S, or P) - -type: keyword - -example: California - --- - -*`threat.indicator.file.x509.not_after`*:: -+ --- -Time at which the certificate is no longer considered valid. - -type: date - -example: 2020-07-16 03:15:39+00:00 - --- - -*`threat.indicator.file.x509.not_before`*:: -+ --- -Time at which the certificate is first considered valid. - -type: date - -example: 2019-08-16 01:40:25+00:00 - --- - -*`threat.indicator.file.x509.public_key_algorithm`*:: -+ --- -Algorithm used to generate the public key. - -type: keyword - -example: RSA - --- - -*`threat.indicator.file.x509.public_key_curve`*:: -+ --- -The curve used by the elliptic curve public key algorithm. This is algorithm specific. - -type: keyword - -example: nistp521 - --- - -*`threat.indicator.file.x509.public_key_exponent`*:: -+ --- -Exponent used to derive the public key. This is algorithm specific. - -type: long - -example: 65537 - -Field is not indexed. - --- - -*`threat.indicator.file.x509.public_key_size`*:: -+ --- -The size of the public key space in bits. - -type: long - -example: 2048 - --- - -*`threat.indicator.file.x509.serial_number`*:: -+ --- -Unique serial number issued by the certificate authority. For consistency, if this value is alphanumeric, it should be formatted without colons and uppercase characters. - -type: keyword - -example: 55FBB9C7DEBF09809D12CCAA - --- - -*`threat.indicator.file.x509.signature_algorithm`*:: -+ --- -Identifier for certificate signature algorithm. We recommend using names found in Go Lang Crypto library. See https://github.com/golang/go/blob/go1.14/src/crypto/x509/x509.go#L337-L353. - -type: keyword - -example: SHA256-RSA - --- - -*`threat.indicator.file.x509.subject.common_name`*:: -+ --- -List of common names (CN) of subject. - -type: keyword - -example: shared.global.example.net - --- - -*`threat.indicator.file.x509.subject.country`*:: -+ --- -List of country (C) code - -type: keyword - -example: US - --- - -*`threat.indicator.file.x509.subject.distinguished_name`*:: -+ --- -Distinguished name (DN) of the certificate subject entity. - -type: keyword - -example: C=US, ST=California, L=San Francisco, O=Example, Inc., CN=shared.global.example.net - --- - -*`threat.indicator.file.x509.subject.locality`*:: -+ --- -List of locality names (L) - -type: keyword - -example: San Francisco - --- - -*`threat.indicator.file.x509.subject.organization`*:: -+ --- -List of organizations (O) of subject. - -type: keyword - -example: Example, Inc. - --- - -*`threat.indicator.file.x509.subject.organizational_unit`*:: -+ --- -List of organizational units (OU) of subject. - -type: keyword - --- - -*`threat.indicator.file.x509.subject.state_or_province`*:: -+ --- -List of state or province names (ST, S, or P) - -type: keyword - -example: California - --- - -*`threat.indicator.file.x509.version_number`*:: -+ --- -Version of x509 format. - -type: keyword - -example: 3 - --- - -*`threat.indicator.first_seen`*:: -+ --- -The date and time when intelligence source first reported sighting this indicator. - -type: date - -example: 2020-11-05T17:25:47.000Z - --- - -*`threat.indicator.geo.city_name`*:: -+ --- -City name. - -type: keyword - -example: Montreal - --- - -*`threat.indicator.geo.continent_code`*:: -+ --- -Two-letter code representing continent's name. - -type: keyword - -example: NA - --- - -*`threat.indicator.geo.continent_name`*:: -+ --- -Name of the continent. - -type: keyword - -example: North America - --- - -*`threat.indicator.geo.country_iso_code`*:: -+ --- -Country ISO code. - -type: keyword - -example: CA - --- - -*`threat.indicator.geo.country_name`*:: -+ --- -Country name. - -type: keyword - -example: Canada - --- - -*`threat.indicator.geo.location`*:: -+ --- -Longitude and latitude. - -type: geo_point - -example: { "lon": -73.614830, "lat": 45.505918 } - --- - -*`threat.indicator.geo.name`*:: -+ --- -User-defined description of a location, at the level of granularity they care about. -Could be the name of their data centers, the floor number, if this describes a local physical entity, city names. -Not typically used in automated geolocation. - -type: keyword - -example: boston-dc - --- - -*`threat.indicator.geo.postal_code`*:: -+ --- -Postal code associated with the location. -Values appropriate for this field may also be known as a postcode or ZIP code and will vary widely from country to country. - -type: keyword - -example: 94040 - --- - -*`threat.indicator.geo.region_iso_code`*:: -+ --- -Region ISO code. - -type: keyword - -example: CA-QC - --- - -*`threat.indicator.geo.region_name`*:: -+ --- -Region name. - -type: keyword - -example: Quebec - --- - -*`threat.indicator.geo.timezone`*:: -+ --- -The time zone of the location, such as IANA time zone name. - -type: keyword - -example: America/Argentina/Buenos_Aires - --- - -*`threat.indicator.ip`*:: -+ --- -Identifies a threat indicator as an IP address (irrespective of direction). - -type: ip - -example: 1.2.3.4 - --- - -*`threat.indicator.last_seen`*:: -+ --- -The date and time when intelligence source last reported sighting this indicator. - -type: date - -example: 2020-11-05T17:25:47.000Z - --- - -*`threat.indicator.marking.tlp`*:: -+ --- -Traffic Light Protocol sharing markings. -Recommended values are: - * WHITE - * GREEN - * AMBER - * RED - -type: keyword - -example: WHITE - --- - -*`threat.indicator.modified_at`*:: -+ --- -The date and time when intelligence source last modified information for this indicator. - -type: date - -example: 2020-11-05T17:25:47.000Z - --- - -*`threat.indicator.port`*:: -+ --- -Identifies a threat indicator as a port number (irrespective of direction). - -type: long - -example: 443 - --- - -*`threat.indicator.provider`*:: -+ --- -The name of the indicator's provider. - -type: keyword - -example: lrz_urlhaus - --- - -*`threat.indicator.reference`*:: -+ --- -Reference URL linking to additional information about this indicator. - -type: keyword - -example: https://system.example.com/indicator/0001234 - --- - -*`threat.indicator.registry.data.bytes`*:: -+ --- -Original bytes written with base64 encoding. -For Windows registry operations, such as SetValueEx and RegQueryValueEx, this corresponds to the data pointed by `lp_data`. This is optional but provides better recoverability and should be populated for REG_BINARY encoded values. - -type: keyword - -example: ZQBuAC0AVQBTAAAAZQBuAAAAAAA= - --- - -*`threat.indicator.registry.data.strings`*:: -+ --- -Content when writing string types. -Populated as an array when writing string data to the registry. For single string registry types (REG_SZ, REG_EXPAND_SZ), this should be an array with one string. For sequences of string with REG_MULTI_SZ, this array will be variable length. For numeric data, such as REG_DWORD and REG_QWORD, this should be populated with the decimal representation (e.g `"1"`). - -type: wildcard - -example: ["C:\rta\red_ttp\bin\myapp.exe"] - --- - -*`threat.indicator.registry.data.type`*:: -+ --- -Standard registry type for encoding contents - -type: keyword - -example: REG_SZ - --- - -*`threat.indicator.registry.hive`*:: -+ --- -Abbreviated name for the hive. - -type: keyword - -example: HKLM - --- - -*`threat.indicator.registry.key`*:: -+ --- -Hive-relative path of keys. - -type: keyword - -example: SOFTWARE\Microsoft\Windows NT\CurrentVersion\Image File Execution Options\winword.exe - --- - -*`threat.indicator.registry.path`*:: -+ --- -Full path, including hive, key and value - -type: keyword - -example: HKLM\SOFTWARE\Microsoft\Windows NT\CurrentVersion\Image File Execution Options\winword.exe\Debugger - --- - -*`threat.indicator.registry.value`*:: -+ --- -Name of the value written. - -type: keyword - -example: Debugger - --- - -*`threat.indicator.scanner_stats`*:: -+ --- -Count of AV/EDR vendors that successfully detected malicious file or URL. - -type: long - -example: 4 - --- - -*`threat.indicator.sightings`*:: -+ --- -Number of times this indicator was observed conducting threat activity. - -type: long - -example: 20 - --- - -*`threat.indicator.type`*:: -+ --- -Type of indicator as represented by Cyber Observable in STIX 2.0. -Recommended values: - * autonomous-system - * artifact - * directory - * domain-name - * email-addr - * file - * ipv4-addr - * ipv6-addr - * mac-addr - * mutex - * port - * process - * software - * url - * user-account - * windows-registry-key - * x509-certificate - -type: keyword - -example: ipv4-addr - --- - -*`threat.indicator.url.domain`*:: -+ --- -Domain of the url, such as "www.elastic.co". -In some cases a URL may refer to an IP and/or port directly, without a domain name. In this case, the IP address would go to the `domain` field. -If the URL contains a literal IPv6 address enclosed by `[` and `]` (IETF RFC 2732), the `[` and `]` characters should also be captured in the `domain` field. - -type: keyword - -example: www.elastic.co - --- - -*`threat.indicator.url.extension`*:: -+ --- -The field contains the file extension from the original request url, excluding the leading dot. -The file extension is only set if it exists, as not every url has a file extension. -The leading period must not be included. For example, the value must be "png", not ".png". -Note that when the file name has multiple extensions (example.tar.gz), only the last one should be captured ("gz", not "tar.gz"). - -type: keyword - -example: png - --- - -*`threat.indicator.url.fragment`*:: -+ --- -Portion of the url after the `#`, such as "top". -The `#` is not part of the fragment. - -type: keyword - --- - -*`threat.indicator.url.full`*:: -+ --- -If full URLs are important to your use case, they should be stored in `url.full`, whether this field is reconstructed or present in the event source. - -type: wildcard - -example: https://www.elastic.co:443/search?q=elasticsearch#top - --- - -*`threat.indicator.url.full.text`*:: -+ --- -type: match_only_text - --- - -*`threat.indicator.url.original`*:: -+ --- -Unmodified original url as seen in the event source. -Note that in network monitoring, the observed URL may be a full URL, whereas in access logs, the URL is often just represented as a path. -This field is meant to represent the URL as it was observed, complete or not. - -type: wildcard - -example: https://www.elastic.co:443/search?q=elasticsearch#top or /search?q=elasticsearch - --- - -*`threat.indicator.url.original.text`*:: -+ --- -type: match_only_text - --- - -*`threat.indicator.url.password`*:: -+ --- -Password of the request. - -type: keyword - --- - -*`threat.indicator.url.path`*:: -+ --- -Path of the request, such as "/search". - -type: wildcard - --- - -*`threat.indicator.url.port`*:: -+ --- -Port of the request, such as 443. - -type: long - -example: 443 - -format: string - --- - -*`threat.indicator.url.query`*:: -+ --- -The query field describes the query string of the request, such as "q=elasticsearch". -The `?` is excluded from the query string. If a URL contains no `?`, there is no query field. If there is a `?` but no query, the query field exists with an empty string. The `exists` query can be used to differentiate between the two cases. - -type: keyword - --- - -*`threat.indicator.url.registered_domain`*:: -+ --- -The highest registered url domain, stripped of the subdomain. -For example, the registered domain for "foo.example.com" is "example.com". -This value can be determined precisely with a list like the public suffix list (http://publicsuffix.org). Trying to approximate this by simply taking the last two labels will not work well for TLDs such as "co.uk". - -type: keyword - -example: example.com - --- - -*`threat.indicator.url.scheme`*:: -+ --- -Scheme of the request, such as "https". -Note: The `:` is not part of the scheme. - -type: keyword - -example: https - --- - -*`threat.indicator.url.subdomain`*:: -+ --- -The subdomain portion of a fully qualified domain name includes all of the names except the host name under the registered_domain. In a partially qualified domain, or if the the qualification level of the full name cannot be determined, subdomain contains all of the names below the registered domain. -For example the subdomain portion of "www.east.mydomain.co.uk" is "east". If the domain has multiple levels of subdomain, such as "sub2.sub1.example.com", the subdomain field should contain "sub2.sub1", with no trailing period. - -type: keyword - -example: east - --- - -*`threat.indicator.url.top_level_domain`*:: -+ --- -The effective top level domain (eTLD), also known as the domain suffix, is the last part of the domain name. For example, the top level domain for example.com is "com". -This value can be determined precisely with a list like the public suffix list (http://publicsuffix.org). Trying to approximate this by simply taking the last label will not work well for effective TLDs such as "co.uk". - -type: keyword - -example: co.uk - --- - -*`threat.indicator.url.username`*:: -+ --- -Username of the request. - -type: keyword - --- - -*`threat.indicator.x509.alternative_names`*:: -+ --- -List of subject alternative names (SAN). Name types vary by certificate authority and certificate type but commonly contain IP addresses, DNS names (and wildcards), and email addresses. - -type: keyword - -example: *.elastic.co - --- - -*`threat.indicator.x509.issuer.common_name`*:: -+ --- -List of common name (CN) of issuing certificate authority. - -type: keyword - -example: Example SHA2 High Assurance Server CA - --- - -*`threat.indicator.x509.issuer.country`*:: -+ --- -List of country (C) codes - -type: keyword - -example: US - --- - -*`threat.indicator.x509.issuer.distinguished_name`*:: -+ --- -Distinguished name (DN) of issuing certificate authority. - -type: keyword - -example: C=US, O=Example Inc, OU=www.example.com, CN=Example SHA2 High Assurance Server CA - --- - -*`threat.indicator.x509.issuer.locality`*:: -+ --- -List of locality names (L) - -type: keyword - -example: Mountain View - --- - -*`threat.indicator.x509.issuer.organization`*:: -+ --- -List of organizations (O) of issuing certificate authority. - -type: keyword - -example: Example Inc - --- - -*`threat.indicator.x509.issuer.organizational_unit`*:: -+ --- -List of organizational units (OU) of issuing certificate authority. - -type: keyword - -example: www.example.com - --- - -*`threat.indicator.x509.issuer.state_or_province`*:: -+ --- -List of state or province names (ST, S, or P) - -type: keyword - -example: California - --- - -*`threat.indicator.x509.not_after`*:: -+ --- -Time at which the certificate is no longer considered valid. - -type: date - -example: 2020-07-16 03:15:39+00:00 - --- - -*`threat.indicator.x509.not_before`*:: -+ --- -Time at which the certificate is first considered valid. - -type: date - -example: 2019-08-16 01:40:25+00:00 - --- - -*`threat.indicator.x509.public_key_algorithm`*:: -+ --- -Algorithm used to generate the public key. - -type: keyword - -example: RSA - --- - -*`threat.indicator.x509.public_key_curve`*:: -+ --- -The curve used by the elliptic curve public key algorithm. This is algorithm specific. - -type: keyword - -example: nistp521 - --- - -*`threat.indicator.x509.public_key_exponent`*:: -+ --- -Exponent used to derive the public key. This is algorithm specific. - -type: long - -example: 65537 - -Field is not indexed. - --- - -*`threat.indicator.x509.public_key_size`*:: -+ --- -The size of the public key space in bits. - -type: long - -example: 2048 - --- - -*`threat.indicator.x509.serial_number`*:: -+ --- -Unique serial number issued by the certificate authority. For consistency, if this value is alphanumeric, it should be formatted without colons and uppercase characters. - -type: keyword - -example: 55FBB9C7DEBF09809D12CCAA - --- - -*`threat.indicator.x509.signature_algorithm`*:: -+ --- -Identifier for certificate signature algorithm. We recommend using names found in Go Lang Crypto library. See https://github.com/golang/go/blob/go1.14/src/crypto/x509/x509.go#L337-L353. - -type: keyword - -example: SHA256-RSA - --- - -*`threat.indicator.x509.subject.common_name`*:: -+ --- -List of common names (CN) of subject. - -type: keyword - -example: shared.global.example.net - --- - -*`threat.indicator.x509.subject.country`*:: -+ --- -List of country (C) code - -type: keyword - -example: US - --- - -*`threat.indicator.x509.subject.distinguished_name`*:: -+ --- -Distinguished name (DN) of the certificate subject entity. - -type: keyword - -example: C=US, ST=California, L=San Francisco, O=Example, Inc., CN=shared.global.example.net - --- - -*`threat.indicator.x509.subject.locality`*:: -+ --- -List of locality names (L) - -type: keyword - -example: San Francisco - --- - -*`threat.indicator.x509.subject.organization`*:: -+ --- -List of organizations (O) of subject. - -type: keyword - -example: Example, Inc. - --- - -*`threat.indicator.x509.subject.organizational_unit`*:: -+ --- -List of organizational units (OU) of subject. - -type: keyword - --- - -*`threat.indicator.x509.subject.state_or_province`*:: -+ --- -List of state or province names (ST, S, or P) - -type: keyword - -example: California - --- - -*`threat.indicator.x509.version_number`*:: -+ --- -Version of x509 format. - -type: keyword - -example: 3 - --- - -*`threat.software.alias`*:: -+ --- -The alias(es) of the software for a set of related intrusion activity that are tracked by a common name in the security community. -While not required, you can use a MITRE ATT&CK® associated software description. - -type: keyword - -example: [ "X-Agent" ] - --- - -*`threat.software.id`*:: -+ --- -The id of the software used by this threat to conduct behavior commonly modeled using MITRE ATT&CK®. -While not required, you can use a MITRE ATT&CK® software id. - -type: keyword - -example: S0552 - --- - -*`threat.software.name`*:: -+ --- -The name of the software used by this threat to conduct behavior commonly modeled using MITRE ATT&CK®. -While not required, you can use a MITRE ATT&CK® software name. - -type: keyword - -example: AdFind - --- - -*`threat.software.platforms`*:: -+ --- -The platforms of the software used by this threat to conduct behavior commonly modeled using MITRE ATT&CK®. -Recommended Values: - * AWS - * Azure - * Azure AD - * GCP - * Linux - * macOS - * Network - * Office 365 - * SaaS - * Windows - -While not required, you can use a MITRE ATT&CK® software platforms. - -type: keyword - -example: [ "Windows" ] - --- - -*`threat.software.reference`*:: -+ --- -The reference URL of the software used by this threat to conduct behavior commonly modeled using MITRE ATT&CK®. -While not required, you can use a MITRE ATT&CK® software reference URL. - -type: keyword - -example: https://attack.mitre.org/software/S0552/ - --- - -*`threat.software.type`*:: -+ --- -The type of software used by this threat to conduct behavior commonly modeled using MITRE ATT&CK®. -Recommended values - * Malware - * Tool - - While not required, you can use a MITRE ATT&CK® software type. - -type: keyword - -example: Tool - --- - -*`threat.tactic.id`*:: -+ --- -The id of tactic used by this threat. You can use a MITRE ATT&CK® tactic, for example. (ex. https://attack.mitre.org/tactics/TA0002/ ) - -type: keyword - -example: TA0002 - --- - -*`threat.tactic.name`*:: -+ --- -Name of the type of tactic used by this threat. You can use a MITRE ATT&CK® tactic, for example. (ex. https://attack.mitre.org/tactics/TA0002/) - -type: keyword - -example: Execution - --- - -*`threat.tactic.reference`*:: -+ --- -The reference url of tactic used by this threat. You can use a MITRE ATT&CK® tactic, for example. (ex. https://attack.mitre.org/tactics/TA0002/ ) - -type: keyword - -example: https://attack.mitre.org/tactics/TA0002/ - --- - -*`threat.technique.id`*:: -+ --- -The id of technique used by this threat. You can use a MITRE ATT&CK® technique, for example. (ex. https://attack.mitre.org/techniques/T1059/) - -type: keyword - -example: T1059 - --- - -*`threat.technique.name`*:: -+ --- -The name of technique used by this threat. You can use a MITRE ATT&CK® technique, for example. (ex. https://attack.mitre.org/techniques/T1059/) - -type: keyword - -example: Command and Scripting Interpreter - --- - -*`threat.technique.name.text`*:: -+ --- -type: match_only_text - --- - -*`threat.technique.reference`*:: -+ --- -The reference url of technique used by this threat. You can use a MITRE ATT&CK® technique, for example. (ex. https://attack.mitre.org/techniques/T1059/) - -type: keyword - -example: https://attack.mitre.org/techniques/T1059/ - --- - -*`threat.technique.subtechnique.id`*:: -+ --- -The full id of subtechnique used by this threat. You can use a MITRE ATT&CK® subtechnique, for example. (ex. https://attack.mitre.org/techniques/T1059/001/) - -type: keyword - -example: T1059.001 - --- - -*`threat.technique.subtechnique.name`*:: -+ --- -The name of subtechnique used by this threat. You can use a MITRE ATT&CK® subtechnique, for example. (ex. https://attack.mitre.org/techniques/T1059/001/) - -type: keyword - -example: PowerShell - --- - -*`threat.technique.subtechnique.name.text`*:: -+ --- -type: match_only_text - --- - -*`threat.technique.subtechnique.reference`*:: -+ --- -The reference url of subtechnique used by this threat. You can use a MITRE ATT&CK® subtechnique, for example. (ex. https://attack.mitre.org/techniques/T1059/001/) - -type: keyword - -example: https://attack.mitre.org/techniques/T1059/001/ - --- - -[float] -=== tls - -Fields related to a TLS connection. These fields focus on the TLS protocol itself and intentionally avoids in-depth analysis of the related x.509 certificate files. - - -*`tls.cipher`*:: -+ --- -String indicating the cipher used during the current connection. - -type: keyword - -example: TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256 - --- - -*`tls.client.certificate`*:: -+ --- -PEM-encoded stand-alone certificate offered by the client. This is usually mutually-exclusive of `client.certificate_chain` since this value also exists in that list. - -type: keyword - -example: MII... - --- - -*`tls.client.certificate_chain`*:: -+ --- -Array of PEM-encoded certificates that make up the certificate chain offered by the client. This is usually mutually-exclusive of `client.certificate` since that value should be the first certificate in the chain. - -type: keyword - -example: ["MII...", "MII..."] - --- - -*`tls.client.hash.md5`*:: -+ --- -Certificate fingerprint using the MD5 digest of DER-encoded version of certificate offered by the client. For consistency with other hash values, this value should be formatted as an uppercase hash. - -type: keyword - -example: 0F76C7F2C55BFD7D8E8B8F4BFBF0C9EC - --- - -*`tls.client.hash.sha1`*:: -+ --- -Certificate fingerprint using the SHA1 digest of DER-encoded version of certificate offered by the client. For consistency with other hash values, this value should be formatted as an uppercase hash. - -type: keyword - -example: 9E393D93138888D288266C2D915214D1D1CCEB2A - --- - -*`tls.client.hash.sha256`*:: -+ --- -Certificate fingerprint using the SHA256 digest of DER-encoded version of certificate offered by the client. For consistency with other hash values, this value should be formatted as an uppercase hash. - -type: keyword - -example: 0687F666A054EF17A08E2F2162EAB4CBC0D265E1D7875BE74BF3C712CA92DAF0 - --- - -*`tls.client.issuer`*:: -+ --- -Distinguished name of subject of the issuer of the x.509 certificate presented by the client. - -type: keyword - -example: CN=Example Root CA, OU=Infrastructure Team, DC=example, DC=com - --- - -*`tls.client.ja3`*:: -+ --- -A hash that identifies clients based on how they perform an SSL/TLS handshake. - -type: keyword - -example: d4e5b18d6b55c71272893221c96ba240 - --- - -*`tls.client.not_after`*:: -+ --- -Date/Time indicating when client certificate is no longer considered valid. - -type: date - -example: 2021-01-01T00:00:00.000Z - --- - -*`tls.client.not_before`*:: -+ --- -Date/Time indicating when client certificate is first considered valid. - -type: date - -example: 1970-01-01T00:00:00.000Z - --- - -*`tls.client.server_name`*:: -+ --- -Also called an SNI, this tells the server which hostname to which the client is attempting to connect to. When this value is available, it should get copied to `destination.domain`. - -type: keyword - -example: www.elastic.co - --- - -*`tls.client.subject`*:: -+ --- -Distinguished name of subject of the x.509 certificate presented by the client. - -type: keyword - -example: CN=myclient, OU=Documentation Team, DC=example, DC=com - --- - -*`tls.client.supported_ciphers`*:: -+ --- -Array of ciphers offered by the client during the client hello. - -type: keyword - -example: ["TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384", "TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384", "..."] - --- - -*`tls.client.x509.alternative_names`*:: -+ --- -List of subject alternative names (SAN). Name types vary by certificate authority and certificate type but commonly contain IP addresses, DNS names (and wildcards), and email addresses. - -type: keyword - -example: *.elastic.co - --- - -*`tls.client.x509.issuer.common_name`*:: -+ --- -List of common name (CN) of issuing certificate authority. - -type: keyword - -example: Example SHA2 High Assurance Server CA - --- - -*`tls.client.x509.issuer.country`*:: -+ --- -List of country (C) codes - -type: keyword - -example: US - --- - -*`tls.client.x509.issuer.distinguished_name`*:: -+ --- -Distinguished name (DN) of issuing certificate authority. - -type: keyword - -example: C=US, O=Example Inc, OU=www.example.com, CN=Example SHA2 High Assurance Server CA - --- - -*`tls.client.x509.issuer.locality`*:: -+ --- -List of locality names (L) - -type: keyword - -example: Mountain View - --- - -*`tls.client.x509.issuer.organization`*:: -+ --- -List of organizations (O) of issuing certificate authority. - -type: keyword - -example: Example Inc - --- - -*`tls.client.x509.issuer.organizational_unit`*:: -+ --- -List of organizational units (OU) of issuing certificate authority. - -type: keyword - -example: www.example.com - --- - -*`tls.client.x509.issuer.state_or_province`*:: -+ --- -List of state or province names (ST, S, or P) - -type: keyword - -example: California - --- - -*`tls.client.x509.not_after`*:: -+ --- -Time at which the certificate is no longer considered valid. - -type: date - -example: 2020-07-16 03:15:39+00:00 - --- - -*`tls.client.x509.not_before`*:: -+ --- -Time at which the certificate is first considered valid. - -type: date - -example: 2019-08-16 01:40:25+00:00 - --- - -*`tls.client.x509.public_key_algorithm`*:: -+ --- -Algorithm used to generate the public key. - -type: keyword - -example: RSA - --- - -*`tls.client.x509.public_key_curve`*:: -+ --- -The curve used by the elliptic curve public key algorithm. This is algorithm specific. - -type: keyword - -example: nistp521 - --- - -*`tls.client.x509.public_key_exponent`*:: -+ --- -Exponent used to derive the public key. This is algorithm specific. - -type: long - -example: 65537 - -Field is not indexed. - --- - -*`tls.client.x509.public_key_size`*:: -+ --- -The size of the public key space in bits. - -type: long - -example: 2048 - --- - -*`tls.client.x509.serial_number`*:: -+ --- -Unique serial number issued by the certificate authority. For consistency, if this value is alphanumeric, it should be formatted without colons and uppercase characters. - -type: keyword - -example: 55FBB9C7DEBF09809D12CCAA - --- - -*`tls.client.x509.signature_algorithm`*:: -+ --- -Identifier for certificate signature algorithm. We recommend using names found in Go Lang Crypto library. See https://github.com/golang/go/blob/go1.14/src/crypto/x509/x509.go#L337-L353. - -type: keyword - -example: SHA256-RSA - --- - -*`tls.client.x509.subject.common_name`*:: -+ --- -List of common names (CN) of subject. - -type: keyword - -example: shared.global.example.net - --- - -*`tls.client.x509.subject.country`*:: -+ --- -List of country (C) code - -type: keyword - -example: US - --- - -*`tls.client.x509.subject.distinguished_name`*:: -+ --- -Distinguished name (DN) of the certificate subject entity. - -type: keyword - -example: C=US, ST=California, L=San Francisco, O=Example, Inc., CN=shared.global.example.net - --- - -*`tls.client.x509.subject.locality`*:: -+ --- -List of locality names (L) - -type: keyword - -example: San Francisco - --- - -*`tls.client.x509.subject.organization`*:: -+ --- -List of organizations (O) of subject. - -type: keyword - -example: Example, Inc. - --- - -*`tls.client.x509.subject.organizational_unit`*:: -+ --- -List of organizational units (OU) of subject. - -type: keyword - --- - -*`tls.client.x509.subject.state_or_province`*:: -+ --- -List of state or province names (ST, S, or P) - -type: keyword - -example: California - --- - -*`tls.client.x509.version_number`*:: -+ --- -Version of x509 format. - -type: keyword - -example: 3 - --- - -*`tls.curve`*:: -+ --- -String indicating the curve used for the given cipher, when applicable. - -type: keyword - -example: secp256r1 - --- - -*`tls.established`*:: -+ --- -Boolean flag indicating if the TLS negotiation was successful and transitioned to an encrypted tunnel. - -type: boolean - --- - -*`tls.next_protocol`*:: -+ --- -String indicating the protocol being tunneled. Per the values in the IANA registry (https://www.iana.org/assignments/tls-extensiontype-values/tls-extensiontype-values.xhtml#alpn-protocol-ids), this string should be lower case. - -type: keyword - -example: http/1.1 - --- - -*`tls.resumed`*:: -+ --- -Boolean flag indicating if this TLS connection was resumed from an existing TLS negotiation. - -type: boolean - --- - -*`tls.server.certificate`*:: -+ --- -PEM-encoded stand-alone certificate offered by the server. This is usually mutually-exclusive of `server.certificate_chain` since this value also exists in that list. - -type: keyword - -example: MII... - --- - -*`tls.server.certificate_chain`*:: -+ --- -Array of PEM-encoded certificates that make up the certificate chain offered by the server. This is usually mutually-exclusive of `server.certificate` since that value should be the first certificate in the chain. - -type: keyword - -example: ["MII...", "MII..."] - --- - -*`tls.server.hash.md5`*:: -+ --- -Certificate fingerprint using the MD5 digest of DER-encoded version of certificate offered by the server. For consistency with other hash values, this value should be formatted as an uppercase hash. - -type: keyword - -example: 0F76C7F2C55BFD7D8E8B8F4BFBF0C9EC - --- - -*`tls.server.hash.sha1`*:: -+ --- -Certificate fingerprint using the SHA1 digest of DER-encoded version of certificate offered by the server. For consistency with other hash values, this value should be formatted as an uppercase hash. - -type: keyword - -example: 9E393D93138888D288266C2D915214D1D1CCEB2A - --- - -*`tls.server.hash.sha256`*:: -+ --- -Certificate fingerprint using the SHA256 digest of DER-encoded version of certificate offered by the server. For consistency with other hash values, this value should be formatted as an uppercase hash. - -type: keyword - -example: 0687F666A054EF17A08E2F2162EAB4CBC0D265E1D7875BE74BF3C712CA92DAF0 - --- - -*`tls.server.issuer`*:: -+ --- -Subject of the issuer of the x.509 certificate presented by the server. - -type: keyword - -example: CN=Example Root CA, OU=Infrastructure Team, DC=example, DC=com - --- - -*`tls.server.ja3s`*:: -+ --- -A hash that identifies servers based on how they perform an SSL/TLS handshake. - -type: keyword - -example: 394441ab65754e2207b1e1b457b3641d - --- - -*`tls.server.not_after`*:: -+ --- -Timestamp indicating when server certificate is no longer considered valid. - -type: date - -example: 2021-01-01T00:00:00.000Z - --- - -*`tls.server.not_before`*:: -+ --- -Timestamp indicating when server certificate is first considered valid. - -type: date - -example: 1970-01-01T00:00:00.000Z - --- - -*`tls.server.subject`*:: -+ --- -Subject of the x.509 certificate presented by the server. - -type: keyword - -example: CN=www.example.com, OU=Infrastructure Team, DC=example, DC=com - --- - -*`tls.server.x509.alternative_names`*:: -+ --- -List of subject alternative names (SAN). Name types vary by certificate authority and certificate type but commonly contain IP addresses, DNS names (and wildcards), and email addresses. - -type: keyword - -example: *.elastic.co - --- - -*`tls.server.x509.issuer.common_name`*:: -+ --- -List of common name (CN) of issuing certificate authority. - -type: keyword - -example: Example SHA2 High Assurance Server CA - --- - -*`tls.server.x509.issuer.country`*:: -+ --- -List of country (C) codes - -type: keyword - -example: US - --- - -*`tls.server.x509.issuer.distinguished_name`*:: -+ --- -Distinguished name (DN) of issuing certificate authority. - -type: keyword - -example: C=US, O=Example Inc, OU=www.example.com, CN=Example SHA2 High Assurance Server CA - --- - -*`tls.server.x509.issuer.locality`*:: -+ --- -List of locality names (L) - -type: keyword - -example: Mountain View - --- - -*`tls.server.x509.issuer.organization`*:: -+ --- -List of organizations (O) of issuing certificate authority. - -type: keyword - -example: Example Inc - --- - -*`tls.server.x509.issuer.organizational_unit`*:: -+ --- -List of organizational units (OU) of issuing certificate authority. - -type: keyword - -example: www.example.com - --- - -*`tls.server.x509.issuer.state_or_province`*:: -+ --- -List of state or province names (ST, S, or P) - -type: keyword - -example: California - --- - -*`tls.server.x509.not_after`*:: -+ --- -Time at which the certificate is no longer considered valid. - -type: date - -example: 2020-07-16 03:15:39+00:00 - --- - -*`tls.server.x509.not_before`*:: -+ --- -Time at which the certificate is first considered valid. - -type: date - -example: 2019-08-16 01:40:25+00:00 - --- - -*`tls.server.x509.public_key_algorithm`*:: -+ --- -Algorithm used to generate the public key. - -type: keyword - -example: RSA - --- - -*`tls.server.x509.public_key_curve`*:: -+ --- -The curve used by the elliptic curve public key algorithm. This is algorithm specific. - -type: keyword - -example: nistp521 - --- - -*`tls.server.x509.public_key_exponent`*:: -+ --- -Exponent used to derive the public key. This is algorithm specific. - -type: long - -example: 65537 - -Field is not indexed. - --- - -*`tls.server.x509.public_key_size`*:: -+ --- -The size of the public key space in bits. - -type: long - -example: 2048 - --- - -*`tls.server.x509.serial_number`*:: -+ --- -Unique serial number issued by the certificate authority. For consistency, if this value is alphanumeric, it should be formatted without colons and uppercase characters. - -type: keyword - -example: 55FBB9C7DEBF09809D12CCAA - --- - -*`tls.server.x509.signature_algorithm`*:: -+ --- -Identifier for certificate signature algorithm. We recommend using names found in Go Lang Crypto library. See https://github.com/golang/go/blob/go1.14/src/crypto/x509/x509.go#L337-L353. - -type: keyword - -example: SHA256-RSA - --- - -*`tls.server.x509.subject.common_name`*:: -+ --- -List of common names (CN) of subject. - -type: keyword - -example: shared.global.example.net - --- - -*`tls.server.x509.subject.country`*:: -+ --- -List of country (C) code - -type: keyword - -example: US - --- - -*`tls.server.x509.subject.distinguished_name`*:: -+ --- -Distinguished name (DN) of the certificate subject entity. - -type: keyword - -example: C=US, ST=California, L=San Francisco, O=Example, Inc., CN=shared.global.example.net - --- - -*`tls.server.x509.subject.locality`*:: -+ --- -List of locality names (L) - -type: keyword - -example: San Francisco - --- - -*`tls.server.x509.subject.organization`*:: -+ --- -List of organizations (O) of subject. - -type: keyword - -example: Example, Inc. - --- - -*`tls.server.x509.subject.organizational_unit`*:: -+ --- -List of organizational units (OU) of subject. - -type: keyword - --- - -*`tls.server.x509.subject.state_or_province`*:: -+ --- -List of state or province names (ST, S, or P) - -type: keyword - -example: California - --- - -*`tls.server.x509.version_number`*:: -+ --- -Version of x509 format. - -type: keyword - -example: 3 - --- - -*`tls.version`*:: -+ --- -Numeric part of the version parsed from the original string. - -type: keyword - -example: 1.2 - --- - -*`tls.version_protocol`*:: -+ --- -Normalized lowercase protocol name parsed from original string. - -type: keyword - -example: tls - --- - -*`span.id`*:: -+ --- -Unique identifier of the span within the scope of its trace. -A span represents an operation within a transaction, such as a request to another service, or a database query. - -type: keyword - -example: 3ff9a8981b7ccd5a - --- - -*`trace.id`*:: -+ --- -Unique identifier of the trace. -A trace groups multiple events like transactions that belong together. For example, a user request handled by multiple inter-connected services. - -type: keyword - -example: 4bf92f3577b34da6a3ce929d0e0e4736 - --- - -*`transaction.id`*:: -+ --- -Unique identifier of the transaction within the scope of its trace. -A transaction is the highest level of work measured within a service, such as a request to a server. - -type: keyword - -example: 00f067aa0ba902b7 - --- - -[float] -=== url - -URL fields provide support for complete or partial URLs, and supports the breaking down into scheme, domain, path, and so on. - - -*`url.domain`*:: -+ --- -Domain of the url, such as "www.elastic.co". -In some cases a URL may refer to an IP and/or port directly, without a domain name. In this case, the IP address would go to the `domain` field. -If the URL contains a literal IPv6 address enclosed by `[` and `]` (IETF RFC 2732), the `[` and `]` characters should also be captured in the `domain` field. - -type: keyword - -example: www.elastic.co - --- - -*`url.extension`*:: -+ --- -The field contains the file extension from the original request url, excluding the leading dot. -The file extension is only set if it exists, as not every url has a file extension. -The leading period must not be included. For example, the value must be "png", not ".png". -Note that when the file name has multiple extensions (example.tar.gz), only the last one should be captured ("gz", not "tar.gz"). - -type: keyword - -example: png - --- - -*`url.fragment`*:: -+ --- -Portion of the url after the `#`, such as "top". -The `#` is not part of the fragment. - -type: keyword - --- - -*`url.full`*:: -+ --- -If full URLs are important to your use case, they should be stored in `url.full`, whether this field is reconstructed or present in the event source. - -type: wildcard - -example: https://www.elastic.co:443/search?q=elasticsearch#top - --- - -*`url.full.text`*:: -+ --- -type: match_only_text - --- - -*`url.original`*:: -+ --- -Unmodified original url as seen in the event source. -Note that in network monitoring, the observed URL may be a full URL, whereas in access logs, the URL is often just represented as a path. -This field is meant to represent the URL as it was observed, complete or not. - -type: wildcard - -example: https://www.elastic.co:443/search?q=elasticsearch#top or /search?q=elasticsearch - --- - -*`url.original.text`*:: -+ --- -type: match_only_text - --- - -*`url.password`*:: -+ --- -Password of the request. - -type: keyword - --- - -*`url.path`*:: -+ --- -Path of the request, such as "/search". - -type: wildcard - --- - -*`url.port`*:: -+ --- -Port of the request, such as 443. - -type: long - -example: 443 - -format: string - --- - -*`url.query`*:: -+ --- -The query field describes the query string of the request, such as "q=elasticsearch". -The `?` is excluded from the query string. If a URL contains no `?`, there is no query field. If there is a `?` but no query, the query field exists with an empty string. The `exists` query can be used to differentiate between the two cases. - -type: keyword - --- - -*`url.registered_domain`*:: -+ --- -The highest registered url domain, stripped of the subdomain. -For example, the registered domain for "foo.example.com" is "example.com". -This value can be determined precisely with a list like the public suffix list (http://publicsuffix.org). Trying to approximate this by simply taking the last two labels will not work well for TLDs such as "co.uk". - -type: keyword - -example: example.com - --- - -*`url.scheme`*:: -+ --- -Scheme of the request, such as "https". -Note: The `:` is not part of the scheme. - -type: keyword - -example: https - --- - -*`url.subdomain`*:: -+ --- -The subdomain portion of a fully qualified domain name includes all of the names except the host name under the registered_domain. In a partially qualified domain, or if the the qualification level of the full name cannot be determined, subdomain contains all of the names below the registered domain. -For example the subdomain portion of "www.east.mydomain.co.uk" is "east". If the domain has multiple levels of subdomain, such as "sub2.sub1.example.com", the subdomain field should contain "sub2.sub1", with no trailing period. - -type: keyword - -example: east - --- - -*`url.top_level_domain`*:: -+ --- -The effective top level domain (eTLD), also known as the domain suffix, is the last part of the domain name. For example, the top level domain for example.com is "com". -This value can be determined precisely with a list like the public suffix list (http://publicsuffix.org). Trying to approximate this by simply taking the last label will not work well for effective TLDs such as "co.uk". - -type: keyword - -example: co.uk - --- - -*`url.username`*:: -+ --- -Username of the request. - -type: keyword - --- - -[float] -=== user - -The user fields describe information about the user that is relevant to the event. -Fields can have one entry or multiple entries. If a user has more than one id, provide an array that includes all of them. - - -*`user.changes.domain`*:: -+ --- -Name of the directory the user is a member of. -For example, an LDAP or Active Directory domain name. - -type: keyword - --- - -*`user.changes.email`*:: -+ --- -User email address. - -type: keyword - --- - -*`user.changes.full_name`*:: -+ --- -User's full name, if available. - -type: keyword - -example: Albert Einstein - --- - -*`user.changes.full_name.text`*:: -+ --- -type: match_only_text - --- - -*`user.changes.group.domain`*:: -+ --- -Name of the directory the group is a member of. -For example, an LDAP or Active Directory domain name. - -type: keyword - --- - -*`user.changes.group.id`*:: -+ --- -Unique identifier for the group on the system/platform. - -type: keyword - --- - -*`user.changes.group.name`*:: -+ --- -Name of the group. - -type: keyword - --- - -*`user.changes.hash`*:: -+ --- -Unique user hash to correlate information for a user in anonymized form. -Useful if `user.id` or `user.name` contain confidential information and cannot be used. - -type: keyword - --- - -*`user.changes.id`*:: -+ --- -Unique identifier of the user. - -type: keyword - -example: S-1-5-21-202424912787-2692429404-2351956786-1000 - --- - -*`user.changes.name`*:: -+ --- -Short name or login of the user. - -type: keyword - -example: a.einstein - --- - -*`user.changes.name.text`*:: -+ --- -type: match_only_text - --- - -*`user.changes.roles`*:: -+ --- -Array of user roles at the time of the event. - -type: keyword - -example: ["kibana_admin", "reporting_user"] - --- - -*`user.domain`*:: -+ --- -Name of the directory the user is a member of. -For example, an LDAP or Active Directory domain name. - -type: keyword - --- - -*`user.effective.domain`*:: -+ --- -Name of the directory the user is a member of. -For example, an LDAP or Active Directory domain name. - -type: keyword - --- - -*`user.effective.email`*:: -+ --- -User email address. - -type: keyword - --- - -*`user.effective.full_name`*:: -+ --- -User's full name, if available. - -type: keyword - -example: Albert Einstein - --- - -*`user.effective.full_name.text`*:: -+ --- -type: match_only_text - --- - -*`user.effective.group.domain`*:: -+ --- -Name of the directory the group is a member of. -For example, an LDAP or Active Directory domain name. - -type: keyword - --- - -*`user.effective.group.id`*:: -+ --- -Unique identifier for the group on the system/platform. - -type: keyword - --- - -*`user.effective.group.name`*:: -+ --- -Name of the group. - -type: keyword - --- - -*`user.effective.hash`*:: -+ --- -Unique user hash to correlate information for a user in anonymized form. -Useful if `user.id` or `user.name` contain confidential information and cannot be used. - -type: keyword - --- - -*`user.effective.id`*:: -+ --- -Unique identifier of the user. - -type: keyword - -example: S-1-5-21-202424912787-2692429404-2351956786-1000 - --- - -*`user.effective.name`*:: -+ --- -Short name or login of the user. - -type: keyword - -example: a.einstein - --- - -*`user.effective.name.text`*:: -+ --- -type: match_only_text - --- - -*`user.effective.roles`*:: -+ --- -Array of user roles at the time of the event. - -type: keyword - -example: ["kibana_admin", "reporting_user"] - --- - -*`user.email`*:: -+ --- -User email address. - -type: keyword - --- - -*`user.full_name`*:: -+ --- -User's full name, if available. - -type: keyword - -example: Albert Einstein - --- - -*`user.full_name.text`*:: -+ --- -type: match_only_text - --- - -*`user.group.domain`*:: -+ --- -Name of the directory the group is a member of. -For example, an LDAP or Active Directory domain name. - -type: keyword - --- - -*`user.group.id`*:: -+ --- -Unique identifier for the group on the system/platform. - -type: keyword - --- - -*`user.group.name`*:: -+ --- -Name of the group. - -type: keyword - --- - -*`user.hash`*:: -+ --- -Unique user hash to correlate information for a user in anonymized form. -Useful if `user.id` or `user.name` contain confidential information and cannot be used. - -type: keyword - --- - -*`user.id`*:: -+ --- -Unique identifier of the user. - -type: keyword - -example: S-1-5-21-202424912787-2692429404-2351956786-1000 - --- - -*`user.name`*:: -+ --- -Short name or login of the user. - -type: keyword - -example: a.einstein - --- - -*`user.name.text`*:: -+ --- -type: match_only_text - --- - -*`user.roles`*:: -+ --- -Array of user roles at the time of the event. - -type: keyword - -example: ["kibana_admin", "reporting_user"] - --- - -*`user.target.domain`*:: -+ --- -Name of the directory the user is a member of. -For example, an LDAP or Active Directory domain name. - -type: keyword - --- - -*`user.target.email`*:: -+ --- -User email address. - -type: keyword - --- - -*`user.target.full_name`*:: -+ --- -User's full name, if available. - -type: keyword - -example: Albert Einstein - --- - -*`user.target.full_name.text`*:: -+ --- -type: match_only_text - --- - -*`user.target.group.domain`*:: -+ --- -Name of the directory the group is a member of. -For example, an LDAP or Active Directory domain name. - -type: keyword - --- - -*`user.target.group.id`*:: -+ --- -Unique identifier for the group on the system/platform. - -type: keyword - --- - -*`user.target.group.name`*:: -+ --- -Name of the group. - -type: keyword - --- - -*`user.target.hash`*:: -+ --- -Unique user hash to correlate information for a user in anonymized form. -Useful if `user.id` or `user.name` contain confidential information and cannot be used. - -type: keyword - --- - -*`user.target.id`*:: -+ --- -Unique identifier of the user. - -type: keyword - -example: S-1-5-21-202424912787-2692429404-2351956786-1000 - --- - -*`user.target.name`*:: -+ --- -Short name or login of the user. - -type: keyword - -example: a.einstein - --- - -*`user.target.name.text`*:: -+ --- -type: match_only_text - --- - -*`user.target.roles`*:: -+ --- -Array of user roles at the time of the event. - -type: keyword - -example: ["kibana_admin", "reporting_user"] - --- - -[float] -=== user_agent - -The user_agent fields normally come from a browser request. -They often show up in web service logs coming from the parsed user agent string. - - -*`user_agent.device.name`*:: -+ --- -Name of the device. - -type: keyword - -example: iPhone - --- - -*`user_agent.name`*:: -+ --- -Name of the user agent. - -type: keyword - -example: Safari - --- - -*`user_agent.original`*:: -+ --- -Unparsed user_agent string. - -type: keyword - -example: Mozilla/5.0 (iPhone; CPU iPhone OS 12_1 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/12.0 Mobile/15E148 Safari/604.1 - --- - -*`user_agent.original.text`*:: -+ --- -type: match_only_text - --- - -*`user_agent.os.family`*:: -+ --- -OS family (such as redhat, debian, freebsd, windows). - -type: keyword - -example: debian - --- - -*`user_agent.os.full`*:: -+ --- -Operating system name, including the version or code name. - -type: keyword - -example: Mac OS Mojave - --- - -*`user_agent.os.full.text`*:: -+ --- -type: match_only_text - --- - -*`user_agent.os.kernel`*:: -+ --- -Operating system kernel version as a raw string. - -type: keyword - -example: 4.4.0-112-generic - --- - -*`user_agent.os.name`*:: -+ --- -Operating system name, without the version. - -type: keyword - -example: Mac OS X - --- - -*`user_agent.os.name.text`*:: -+ --- -type: match_only_text - --- - -*`user_agent.os.platform`*:: -+ --- -Operating system platform (such centos, ubuntu, windows). - -type: keyword - -example: darwin - --- - -*`user_agent.os.type`*:: -+ --- -Use the `os.type` field to categorize the operating system into one of the broad commercial families. -One of these following values should be used (lowercase): linux, macos, unix, windows. -If the OS you're dealing with is not in the list, the field should not be populated. Please let us know by opening an issue with ECS, to propose its addition. - -type: keyword - -example: macos - --- - -*`user_agent.os.version`*:: -+ --- -Operating system version as a raw string. - -type: keyword - -example: 10.14.1 - --- - -*`user_agent.version`*:: -+ --- -Version of the user agent. - -type: keyword - -example: 12.0 - --- - -[float] -=== vlan - -The VLAN fields are used to identify 802.1q tag(s) of a packet, as well as ingress and egress VLAN associations of an observer in relation to a specific packet or connection. -Network.vlan fields are used to record a single VLAN tag, or the outer tag in the case of q-in-q encapsulations, for a packet or connection as observed, typically provided by a network sensor (e.g. Zeek, Wireshark) passively reporting on traffic. -Network.inner VLAN fields are used to report inner q-in-q 802.1q tags (multiple 802.1q encapsulations) as observed, typically provided by a network sensor (e.g. Zeek, Wireshark) passively reporting on traffic. Network.inner VLAN fields should only be used in addition to network.vlan fields to indicate q-in-q tagging. -Observer.ingress and observer.egress VLAN values are used to record observer specific information when observer events contain discrete ingress and egress VLAN information, typically provided by firewalls, routers, or load balancers. - - -*`vlan.id`*:: -+ --- -VLAN ID as reported by the observer. - -type: keyword - -example: 10 - --- - -*`vlan.name`*:: -+ --- -Optional VLAN name as reported by the observer. - -type: keyword - -example: outside - --- - -[float] -=== vulnerability - -The vulnerability fields describe information about a vulnerability that is relevant to an event. - - -*`vulnerability.category`*:: -+ --- -The type of system or architecture that the vulnerability affects. These may be platform-specific (for example, Debian or SUSE) or general (for example, Database or Firewall). For example (https://qualysguard.qualys.com/qwebhelp/fo_portal/knowledgebase/vulnerability_categories.htm[Qualys vulnerability categories]) -This field must be an array. - -type: keyword - -example: ["Firewall"] - --- - -*`vulnerability.classification`*:: -+ --- -The classification of the vulnerability scoring system. For example (https://www.first.org/cvss/) - -type: keyword - -example: CVSS - --- - -*`vulnerability.description`*:: -+ --- -The description of the vulnerability that provides additional context of the vulnerability. For example (https://cve.mitre.org/about/faqs.html#cve_entry_descriptions_created[Common Vulnerabilities and Exposure CVE description]) - -type: keyword - -example: In macOS before 2.12.6, there is a vulnerability in the RPC... - --- - -*`vulnerability.description.text`*:: -+ --- -type: match_only_text - --- - -*`vulnerability.enumeration`*:: -+ --- -The type of identifier used for this vulnerability. For example (https://cve.mitre.org/about/) - -type: keyword - -example: CVE - --- - -*`vulnerability.id`*:: -+ --- -The identification (ID) is the number portion of a vulnerability entry. It includes a unique identification number for the vulnerability. For example (https://cve.mitre.org/about/faqs.html#what_is_cve_id)[Common Vulnerabilities and Exposure CVE ID] - -type: keyword - -example: CVE-2019-00001 - --- - -*`vulnerability.reference`*:: -+ --- -A resource that provides additional information, context, and mitigations for the identified vulnerability. - -type: keyword - -example: https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2019-6111 - --- - -*`vulnerability.report_id`*:: -+ --- -The report or scan identification number. - -type: keyword - -example: 20191018.0001 - --- - -*`vulnerability.scanner.vendor`*:: -+ --- -The name of the vulnerability scanner vendor. - -type: keyword - -example: Tenable - --- - -*`vulnerability.score.base`*:: -+ --- -Scores can range from 0.0 to 10.0, with 10.0 being the most severe. -Base scores cover an assessment for exploitability metrics (attack vector, complexity, privileges, and user interaction), impact metrics (confidentiality, integrity, and availability), and scope. For example (https://www.first.org/cvss/specification-document) - -type: float - -example: 5.5 - --- - -*`vulnerability.score.environmental`*:: -+ --- -Scores can range from 0.0 to 10.0, with 10.0 being the most severe. -Environmental scores cover an assessment for any modified Base metrics, confidentiality, integrity, and availability requirements. For example (https://www.first.org/cvss/specification-document) - -type: float - -example: 5.5 - --- - -*`vulnerability.score.temporal`*:: -+ --- -Scores can range from 0.0 to 10.0, with 10.0 being the most severe. -Temporal scores cover an assessment for code maturity, remediation level, and confidence. For example (https://www.first.org/cvss/specification-document) - -type: float - --- - -*`vulnerability.score.version`*:: -+ --- -The National Vulnerability Database (NVD) provides qualitative severity rankings of "Low", "Medium", and "High" for CVSS v2.0 base score ranges in addition to the severity ratings for CVSS v3.0 as they are defined in the CVSS v3.0 specification. -CVSS is owned and managed by FIRST.Org, Inc. (FIRST), a US-based non-profit organization, whose mission is to help computer security incident response teams across the world. For example (https://nvd.nist.gov/vuln-metrics/cvss) - -type: keyword - -example: 2.0 - --- - -*`vulnerability.severity`*:: -+ --- -The severity of the vulnerability can help with metrics and internal prioritization regarding remediation. For example (https://nvd.nist.gov/vuln-metrics/cvss) - -type: keyword - -example: Critical - --- - -[float] -=== x509 - -This implements the common core fields for x509 certificates. This information is likely logged with TLS sessions, digital signatures found in executable binaries, S/MIME information in email bodies, or analysis of files on disk. -When the certificate relates to a file, use the fields at `file.x509`. When hashes of the DER-encoded certificate are available, the `hash` data set should be populated as well (e.g. `file.hash.sha256`). -Events that contain certificate information about network connections, should use the x509 fields under the relevant TLS fields: `tls.server.x509` and/or `tls.client.x509`. - - -*`x509.alternative_names`*:: -+ --- -List of subject alternative names (SAN). Name types vary by certificate authority and certificate type but commonly contain IP addresses, DNS names (and wildcards), and email addresses. - -type: keyword - -example: *.elastic.co - --- - -*`x509.issuer.common_name`*:: -+ --- -List of common name (CN) of issuing certificate authority. - -type: keyword - -example: Example SHA2 High Assurance Server CA - --- - -*`x509.issuer.country`*:: -+ --- -List of country (C) codes - -type: keyword - -example: US - --- - -*`x509.issuer.distinguished_name`*:: -+ --- -Distinguished name (DN) of issuing certificate authority. - -type: keyword - -example: C=US, O=Example Inc, OU=www.example.com, CN=Example SHA2 High Assurance Server CA - --- - -*`x509.issuer.locality`*:: -+ --- -List of locality names (L) - -type: keyword - -example: Mountain View - --- - -*`x509.issuer.organization`*:: -+ --- -List of organizations (O) of issuing certificate authority. - -type: keyword - -example: Example Inc - --- - -*`x509.issuer.organizational_unit`*:: -+ --- -List of organizational units (OU) of issuing certificate authority. - -type: keyword - -example: www.example.com - --- - -*`x509.issuer.state_or_province`*:: -+ --- -List of state or province names (ST, S, or P) - -type: keyword - -example: California - --- - -*`x509.not_after`*:: -+ --- -Time at which the certificate is no longer considered valid. - -type: date - -example: 2020-07-16 03:15:39+00:00 - --- - -*`x509.not_before`*:: -+ --- -Time at which the certificate is first considered valid. - -type: date - -example: 2019-08-16 01:40:25+00:00 - --- - -*`x509.public_key_algorithm`*:: -+ --- -Algorithm used to generate the public key. - -type: keyword - -example: RSA - --- - -*`x509.public_key_curve`*:: -+ --- -The curve used by the elliptic curve public key algorithm. This is algorithm specific. - -type: keyword - -example: nistp521 - --- - -*`x509.public_key_exponent`*:: -+ --- -Exponent used to derive the public key. This is algorithm specific. - -type: long - -example: 65537 - -Field is not indexed. - --- - -*`x509.public_key_size`*:: -+ --- -The size of the public key space in bits. - -type: long - -example: 2048 - --- - -*`x509.serial_number`*:: -+ --- -Unique serial number issued by the certificate authority. For consistency, if this value is alphanumeric, it should be formatted without colons and uppercase characters. - -type: keyword - -example: 55FBB9C7DEBF09809D12CCAA - --- - -*`x509.signature_algorithm`*:: -+ --- -Identifier for certificate signature algorithm. We recommend using names found in Go Lang Crypto library. See https://github.com/golang/go/blob/go1.14/src/crypto/x509/x509.go#L337-L353. - -type: keyword - -example: SHA256-RSA - --- - -*`x509.subject.common_name`*:: -+ --- -List of common names (CN) of subject. - -type: keyword - -example: shared.global.example.net - --- - -*`x509.subject.country`*:: -+ --- -List of country (C) code - -type: keyword - -example: US - --- - -*`x509.subject.distinguished_name`*:: -+ --- -Distinguished name (DN) of the certificate subject entity. - -type: keyword - -example: C=US, ST=California, L=San Francisco, O=Example, Inc., CN=shared.global.example.net - --- - -*`x509.subject.locality`*:: -+ --- -List of locality names (L) - -type: keyword - -example: San Francisco - --- - -*`x509.subject.organization`*:: -+ --- -List of organizations (O) of subject. - -type: keyword - -example: Example, Inc. - --- - -*`x509.subject.organizational_unit`*:: -+ --- -List of organizational units (OU) of subject. - -type: keyword - --- - -*`x509.subject.state_or_province`*:: -+ --- -List of state or province names (ST, S, or P) - -type: keyword - -example: California - --- - -*`x509.version_number`*:: -+ --- -Version of x509 format. - -type: keyword - -example: 3 - --- - -[[exported-fields-functionbeat]] -== Functionbeat fields - -None - -[[exported-fields-host-processor]] -== Host fields - -Info collected for the host machine. - - - - -*`host.containerized`*:: -+ --- -If the host is a container. - - -type: boolean - --- - -*`host.os.build`*:: -+ --- -OS build information. - - -type: keyword - -example: 18D109 - --- - -*`host.os.codename`*:: -+ --- -OS codename, if any. - - -type: keyword - -example: stretch - --- - -[[exported-fields-jolokia-autodiscover]] -== Jolokia Discovery autodiscover provider fields - -Metadata from Jolokia Discovery added by the jolokia provider. - - - -*`jolokia.agent.version`*:: -+ --- -Version number of jolokia agent. - - -type: keyword - --- - -*`jolokia.agent.id`*:: -+ --- -Each agent has a unique id which can be either provided during startup of the agent in form of a configuration parameter or being autodetected. If autodected, the id has several parts: The IP, the process id, hashcode of the agent and its type. - - -type: keyword - --- - -*`jolokia.server.product`*:: -+ --- -The container product if detected. - - -type: keyword - --- - -*`jolokia.server.version`*:: -+ --- -The container's version (if detected). - - -type: keyword - --- - -*`jolokia.server.vendor`*:: -+ --- -The vendor of the container the agent is running in. - - -type: keyword - --- - -*`jolokia.url`*:: -+ --- -The URL how this agent can be contacted. - - -type: keyword - --- - -*`jolokia.secured`*:: -+ --- -Whether the agent was configured for authentication or not. - - -type: boolean - --- - -[[exported-fields-kubernetes-processor]] -== Kubernetes fields - -Kubernetes metadata added by the kubernetes processor - - - - -*`kubernetes.pod.name`*:: -+ --- -Kubernetes pod name - - -type: keyword - --- - -*`kubernetes.pod.uid`*:: -+ --- -Kubernetes Pod UID - - -type: keyword - --- - -*`kubernetes.pod.ip`*:: -+ --- -Kubernetes Pod IP - - -type: ip - --- - -*`kubernetes.namespace`*:: -+ --- -Kubernetes namespace - - -type: keyword - --- - -*`kubernetes.node.name`*:: -+ --- -Kubernetes node name - - -type: keyword - --- - -*`kubernetes.node.hostname`*:: -+ --- -Kubernetes hostname as reported by the node’s kernel - - -type: keyword - --- - -*`kubernetes.labels.*`*:: -+ --- -Kubernetes labels map - - -type: object - --- - -*`kubernetes.annotations.*`*:: -+ --- -Kubernetes annotations map - - -type: object - --- - -*`kubernetes.selectors.*`*:: -+ --- -Kubernetes selectors map - - -type: object - --- - -*`kubernetes.replicaset.name`*:: -+ --- -Kubernetes replicaset name - - -type: keyword - --- - -*`kubernetes.deployment.name`*:: -+ --- -Kubernetes deployment name - - -type: keyword - --- - -*`kubernetes.statefulset.name`*:: -+ --- -Kubernetes statefulset name - - -type: keyword - --- - -*`kubernetes.container.name`*:: -+ --- -Kubernetes container name (different than the name from the runtime) - - -type: keyword - --- - -[[exported-fields-process]] -== Process fields - -Process metadata fields - - - - -*`process.exe`*:: -+ --- -type: alias - -alias to: process.executable - --- - -[float] -=== owner - -Process owner information. - - -*`process.owner.id`*:: -+ --- -Unique identifier of the user. - -type: keyword - --- - -*`process.owner.name`*:: -+ --- -Short name or login of the user. - -type: keyword - -example: albert - --- - -*`process.owner.name.text`*:: -+ --- -type: text - --- - -:edit_url!: \ No newline at end of file diff --git a/x-pack/functionbeat/docs/filtering.asciidoc b/x-pack/functionbeat/docs/filtering.asciidoc deleted file mode 100644 index c22366c0ee7a..000000000000 --- a/x-pack/functionbeat/docs/filtering.asciidoc +++ /dev/null @@ -1,30 +0,0 @@ -[[filtering-and-enhancing-data]] -[role="xpack"] -== Filter and enhance data with processors - -++++ -Processors -++++ - -Your use case might require only a subset of the data exported by {beatname_uc}, -or you might need to enhance the exported data (for example, by adding -metadata). {beatname_uc} provides a couple of options for filtering and -enhancing exported data. - -You can specify a <<{beatname_lc}-filter_pattern,`filter_pattern`>> to match the -data you want to send. This approach may reduce execution costs because the -function running {beatname_uc} only executes if there is data that matches the -pattern. - -Another approach (the one described here) is to define processors. - - -[float] -[[using-processors]] -=== Processors - -include::{libbeat-dir}/processors.asciidoc[] - -:processor-scope: function -include::{libbeat-dir}/processors-using.asciidoc[] -:processor-scope!: diff --git a/x-pack/functionbeat/docs/general-options.asciidoc b/x-pack/functionbeat/docs/general-options.asciidoc deleted file mode 100644 index 5b21951bcfd9..000000000000 --- a/x-pack/functionbeat/docs/general-options.asciidoc +++ /dev/null @@ -1,13 +0,0 @@ -[[configuration-general-options]] -[role="xpack"] -== Configure general settings - -++++ -General settings -++++ - -You can specify settings in the +{beatname_lc}.yml+ config file to control the -general behavior of {beatname_uc}. - -include::{libbeat-dir}/generalconfig.asciidoc[] - diff --git a/x-pack/functionbeat/docs/getting-started.asciidoc b/x-pack/functionbeat/docs/getting-started.asciidoc deleted file mode 100644 index adbf4ec67174..000000000000 --- a/x-pack/functionbeat/docs/getting-started.asciidoc +++ /dev/null @@ -1,167 +0,0 @@ -[id="{beatname_lc}-installation-configuration"] -[role="xpack"] -== {beatname_uc} quick start: installation and configuration - -++++ -Quick start: installation and configuration -++++ - -This guide describes how to get started quickly monitoring data from your cloud -services. You'll learn how to: - - -* download the {beatname_uc} distribution -* configure details about the cloud functions you want to deploy, including the -services to monitor and triggers -* deploy the cloud functions to your serverless environment -* collect data from cloud services and ship it to the {stack} -* visualize the data in {kib} - -[float] -[[install]] -=== Step 1: Download {beatname_uc} - -The {beatname_uc} distribution contains the command line tools, configuration -file, and binary code required to run {beatname_uc} in your serverless -environment. - -To download and extract the package, use the commands that work with your -system. - -include::{libbeat-dir}/tab-widgets/install-linux-mac-win-short-widget.asciidoc[] - -The commands shown are for AMD platforms, but ARM packages are also available. -Refer to the https://www.elastic.co/downloads/beats/{beatname_lc}[download page] -for the full list of available packages. - -[float] -[[set-connection]] -=== Step 2: Connect to the {stack} - -include::{libbeat-dir}/shared/connecting-to-es.asciidoc[] - -[float] -[[configuration]] -=== Step 3: Configure cloud functions - -Before deploying {beatname_uc} to your cloud provider, you need to specify -details about the cloud functions that you want to deploy, including the -function name and type, and the triggers that will cause the function to -execute. - -In +{beatname_lc}.yml+, configure the functions that you want to deploy. The -configuration settings vary depending on the type of function and cloud provider -you're using. This section provides a an AWS example configuration. - -This example configures a function called `cloudwatch` that collects events from -CloudWatch Logs. When a message is sent to the specified log group, the cloud -function executes and sends message events to the configured output: - -["source","sh",subs="attributes"] -------------------------------------------------------------------------------------- -{beatname_lc}.provider.aws.endpoint: "s3.amazonaws.com" -{beatname_lc}.provider.aws.deploy_bucket: "functionbeat-deploy" <1> -{beatname_lc}.provider.aws.functions: - - name: cloudwatch <2> - enabled: true - type: cloudwatch_logs - description: "lambda function for cloudwatch logs" - triggers: - - log_group_name: /aws/lambda/my-lambda-function -------------------------------------------------------------------------------------- -<1> A unique name for the S3 bucket to which the functions will be -uploaded. -<2> Details about the function you want to deploy, including the name of the -function, the type of service to monitor, and the log groups that trigger the -function. - -See <> for more examples. - -include::{libbeat-dir}/shared/config-check.asciidoc[] - -[float] -[[setup-assets]] -=== Step 4: Set up assets - -{beatname_uc} comes with predefined assets for parsing, indexing, and -visualizing your data. To load these assets: - -. Make sure the user specified in +{beatname_lc}.yml+ is -<>. - -. From the installation directory, run: -+ --- -include::{libbeat-dir}/tab-widgets/setup-linux-mac-win-widget.asciidoc[] --- -+ -`-e` is optional and sends output to standard error instead of the configured log output. - -This step loads the recommended {ref}/index-templates.html[index template] for writing to {es}. - -[TIP] -===== -A connection to {es} (or {ess}) is required to set up the initial -environment. If you're using a different output, such as {ls}, see -<>. -===== - -[float] -[id="{beatname_lc}-deploying"] -[role="xpack"] -=== Step 5: Deploy {beatname_uc} - -To deploy {beatname_uc} functions to your cloud provider, either use the -{beatname_uc} manager, as described here, or <>. - -TIP: If you change the configuration after deploying the function, use -the <> to update your deployment. - -[float] -[[deploy-to-aws]] -==== Deploy to AWS - -. Make sure you have the credentials required to authenticate with AWS. You can -set environment variables that contain your credentials: -+ --- -include::tab-widgets/credentials-aws-widget.asciidoc[] --- -+ -Set `AWS_DEFAULT_REGION` to the region where your services are running. - -. Make sure the user has the permissions required to deploy and run the -function. For more information, see <>. - -. Deploy the cloud functions. -+ -For example, the following command deploys a function called `cloudwatch`: -+ --- -include::tab-widgets/deploy-aws-widget.asciidoc[] --- -+ -The function is deployed to AWS and ready to send log events to the configured -output. -+ -If deployment fails, see <> for help troubleshooting. - -:fnexample!: - -[float] -[[view-data]] -=== Step 6: View your data in {kib} - -There are currently no example dashboards available for {beatname_uc}. - -To learn how to view and explore your data, see the -_{kibana-ref}/index.html[{kib} User Guide]_. - -[float] -=== What's next? - -Now that you have your cloud data streaming into {es}, learn how to unify your -logs, metrics, uptime, and application performance data. - -include::{libbeat-dir}/shared/obs-apps.asciidoc[] diff --git a/x-pack/functionbeat/docs/howto/howto.asciidoc b/x-pack/functionbeat/docs/howto/howto.asciidoc deleted file mode 100644 index f116bc57d0c2..000000000000 --- a/x-pack/functionbeat/docs/howto/howto.asciidoc +++ /dev/null @@ -1,42 +0,0 @@ -[[howto-guides]] -[role="xpack"] -= How to guides - -[partintro] --- -Learn how to perform common {beatname_uc} configuration tasks. - -* <<{beatname_lc}-template>> -* <> -* <<{beatname_lc}-geoip>> -* <> -* <> -* <> - - --- - -[role="xpack"] -include::{libbeat-dir}/howto/load-index-templates.asciidoc[] - -[role="xpack"] -include::{libbeat-dir}/howto/change-index-name.asciidoc[] - -[role="xpack"] -include::{libbeat-dir}/shared-geoip.asciidoc[] - -:standalone: -[role="xpack"] -include::{libbeat-dir}/shared-env-vars.asciidoc[] -:standalone!: - -[role="xpack"] -include::{libbeat-dir}/shared-config-ingest.asciidoc[] - -:standalone: -[role="xpack"] -include::{libbeat-dir}/yaml.asciidoc[] -:standalone!: - - - diff --git a/x-pack/functionbeat/docs/iam-permissions.asciidoc b/x-pack/functionbeat/docs/iam-permissions.asciidoc deleted file mode 100644 index 606f3c792392..000000000000 --- a/x-pack/functionbeat/docs/iam-permissions.asciidoc +++ /dev/null @@ -1,134 +0,0 @@ -[[iam-permissions]] -[role="xpack"] -=== IAM permissions required to deploy {beatname_uc} - -++++ -IAM permissions required for deployment -++++ - -This section describes the minimum privileges or roles required to deploy -functions to your cloud provider. - -[[iam-permissions-aws]] -==== Permissions required by AWS - -The list of required permissions depends on the type of events that you are -collecting. Here are some example policies that grant the required privileges. - -[[iam-permissions-cloudwatch]] -===== CloudWatch logs - -The following policy grants the permissions required to deploy and run a Lambda -function that collects events from CloudWatch logs. - -[source,yaml] ----- -{ - "Version": "2012-10-17", - "Statement": [ - { - "Sid": "VisualEditor0", - "Effect": "Allow", - "Action": [ - "cloudformation:CreateStack", - "cloudformation:DeleteStack", - "cloudformation:DescribeStacks", - "cloudformation:DescribeStackEvents", - "cloudformation:DescribeStackResources", - "cloudformation:GetTemplate", - "cloudformation:UpdateStack", - "cloudformation:ValidateTemplate", - "iam:CreateRole", - "iam:DeleteRole", - "iam:DeleteRolePolicy", - "iam:GetRole", - "iam:GetRolePolicy", - "iam:PassRole", - "iam:PutRolePolicy", - "lambda:AddPermission", - "lambda:CreateFunction", - "lambda:DeleteFunction", - "lambda:GetFunction", - "lambda:GetFunctionConfiguration", - "lambda:PutFunctionConcurrency", - "lambda:RemovePermission", - "lambda:UpdateFunctionCode", - "lambda:UpdateFunctionConfiguration", - "logs:CreateLogGroup", - "logs:DeleteLogGroup", - "logs:DeleteSubscriptionFilter", - "logs:DescribeLogGroups", - "logs:PutSubscriptionFilter", - "s3:CreateBucket", - "s3:DeleteObject", - "s3:ListBucket", - "s3:PutObject", - "s3:GetObject", - "ec2:DescribeSecurityGroups", - "ec2:DescribeSubnets", - "ec2:DescribeVpcs" - ], - "Resource": "*" - } - ] -} ----- - -[[iam-permissions-sqs-kinesis]] -===== SQS and Kinesis - -The following policy grants the permissions required to deploy and run a Lambda -function that reads from SQS queues or Kinesis data streams. - -[source,yaml] ----- -{ - "Version": "2012-10-17", - "Statement": [ - { - "Sid": "VisualEditor0", - "Effect": "Allow", - "Action": [ - "cloudformation:CreateStack", - "cloudformation:DeleteStack", - "cloudformation:DescribeStacks", - "cloudformation:DescribeStackEvents", - "cloudformation:DescribeStackResources", - "cloudformation:GetTemplate", - "cloudformation:UpdateStack", - "cloudformation:ValidateTemplate", - "iam:CreateRole", - "iam:DeleteRole", - "iam:DeleteRolePolicy", - "iam:GetRole", - "iam:GetRolePolicy", - "iam:PassRole", - "iam:PutRolePolicy", - "lambda:AddPermission", - "lambda:CreateFunction", - "lambda:CreateEventSourceMapping", - "lambda:DeleteFunction", - "lambda:DeleteEventSourceMapping", - "lambda:GetEventSourceMapping", - "lambda:GetFunction", - "lambda:GetFunctionConfiguration", - "lambda:PutFunctionConcurrency", - "lambda:RemovePermission", - "lambda:UpdateFunctionCode", - "lambda:UpdateFunctionConfiguration", - "logs:DescribeLogGroups", - "logs:CreateLogGroup", - "s3:CreateBucket", - "s3:DeleteObject", - "s3:ListBucket", - "s3:PutObject", - "s3:GetObject", - "ec2:DescribeSecurityGroups", - "ec2:DescribeSubnets", - "ec2:DescribeVpcs" - ], - "Resource": "*" - } - ] -} ----- diff --git a/x-pack/functionbeat/docs/images/coordinate-map.png b/x-pack/functionbeat/docs/images/coordinate-map.png deleted file mode 100644 index 8ac69fe747cfda15ef0eddcf617e18914409b970..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 370029 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

VC(~Wk}*sj{oYoO>%PA;~k!E#ln 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�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�Y)=cFN$-E4 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͜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 mfguYFSzyQlLly{F;Qs+MHH%8#Dv;>_0000 - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - diff --git a/x-pack/functionbeat/docs/images/functionbeat-pipeline-cloudwatchlogs.png b/x-pack/functionbeat/docs/images/functionbeat-pipeline-cloudwatchlogs.png deleted file mode 100644 index d020044eb98a5743d07e64d36583eb5126664282..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 82236 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%0D!qF7omEAFz?XHw`T7)uT&< z^Fg3wxe<|=NaDoJP2=4BFoA>=}X5INY^JCUMYcCeIclYkD zu6pXJ>T0rIE~$>J>XrG^Cv(9hi!9_rI`b!P!Z6t;zQA&>tPcL#w=`x3nffKU(mZ!r z%B0eplA6U5HM65>(j`wQ(Sf_PVBm40QmW--47zzy%x!>o?Q(KZaPStNWYqMz`f^<7 zbW7B4x0D_`mj1ro>C=)6Eo=5+rth+M7opN#%`S@dD76Snct+_4MwRsi1qEi&!E8Wb zX9B$p>cI%Tf{n!%R8)*Ke3AoL8ZZD_sxd$}gHizpBTUvUcTR?eIbq-O%Cp-nwK;wf z6oJ{OtE;Q1P+%&k0QbXSy!FiTcjKr>MJpfzyA zf{hv|m+0bB|AXiTKbPQQ`)$%dAt=^>sXIPC4(@2~{##L532o86{byUIM+6_!M*X57 zPR*mtyz@-l@fvnJI8at<-E>Pu5mT%{8Xbe=1)-AOE190fr{aaScp@zBP1VnShM5%0 zNKOKszu0i#bz0vqHJV7IYG~*;V*^LVKaim1aARp`zk&UHc{66RbbW4R9A}?4w?5_{ zl)*c^>x~SY6uebu5A&ml7tmfoGzpxshxCiYqO!)ji8n2>IWNYVvYI7L`1|;g5>#`J z_jTZ4wp7Svz;`H2 zcSD)LmIkox{zXX}C{`32H0=+Eyb~Q(2;>Mnc>g;3eL@?olV9wyig$}Y!AHyP*QqXT zK`c$%df#hm^qES!=TH@qg9ROlXUFs6b-rBmJ^HLP6>q)bYMMXqEF+&?+bi~VsF@QVOUUSaj8r%+4^ORqRY?m14a06KQTy2 zS>93NJ1JG9+tEqm#}2cbH4@)WSvk`S3<}C&IoR4NAQ}fgCsS{EO-& $t5Mw`2rfna&LSBz5Gc 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 diff --git a/x-pack/functionbeat/docs/images/functionbeat-pipeline-sqs.png b/x-pack/functionbeat/docs/images/functionbeat-pipeline-sqs.png deleted file mode 100644 index 85ce2764369ee3a66cda6651aaae8044d12c2e32..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 81731 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�c{@&GlDmD$9xdM6)uw$q}4mHgJ1 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%0DcSo6(2ubkPV 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 diff --git a/x-pack/functionbeat/docs/index.asciidoc b/x-pack/functionbeat/docs/index.asciidoc deleted file mode 100644 index 3ab8578a0bc2..000000000000 --- a/x-pack/functionbeat/docs/index.asciidoc +++ /dev/null @@ -1,64 +0,0 @@ -= Functionbeat Reference - -:libbeat-dir: {docdir}/../../../libbeat/docs - -include::{libbeat-dir}/version.asciidoc[] - -include::{asciidoc-dir}/../../shared/versions/stack/{source_branch}.asciidoc[] - -include::{asciidoc-dir}/../../shared/attributes.asciidoc[] - -:beatname_lc: functionbeat -:beatname_uc: Functionbeat -:beatname_pkg: {beatname_lc} -:github_repo_name: beats -:discuss_forum: beats/{beatname_lc} -:beat_default_index_prefix: {beatname_lc} -:has_ml_jobs: no -:libbeat-docs: Beats Platform Reference -:cloudformation-ref: https://aws.amazon.com/cloudformation/[AWS CloudFormation] -:no_kafka_output: -:no_redis_output: -:no_file_output: -:requires_xpack: -:serverless: -:mac_os: -:win_os: -:linux_os: -:no_cache_processor: -:no_dashboards: -:no_repos: -:no_decode_cef_processor: -:no_decode_csv_fields_processor: -:no_parse_aws_vpc_flow_log_processor: -:no_script_processor: -:no_timestamp_processor: -:no_keystore: -:no_add_session_metadata_processor: - -include::{libbeat-dir}/shared-beats-attributes.asciidoc[] - -include::./overview.asciidoc[] - -include::./getting-started.asciidoc[] - -include::./setting-up-running.asciidoc[] - -include::./configuring-howto.asciidoc[] - -include::{docdir}/howto/howto.asciidoc[] - -[role="xpack"] -include::./fields.asciidoc[] - -[role="xpack"] -include::{libbeat-dir}/monitoring/monitoring-beats.asciidoc[] - -[role="xpack"] -include::{libbeat-dir}/shared-securing-beat.asciidoc[] - -include::./troubleshooting.asciidoc[] - -include::./faq.asciidoc[] - - diff --git a/x-pack/functionbeat/docs/overview.asciidoc b/x-pack/functionbeat/docs/overview.asciidoc deleted file mode 100644 index 456b9795ce7a..000000000000 --- a/x-pack/functionbeat/docs/overview.asciidoc +++ /dev/null @@ -1,99 +0,0 @@ -[id="{beatname_lc}-overview"] -[role="xpack"] -== {beatname_uc} overview - -IMPORTANT: Beginning with version 8.10.4 the {beatname_uc} documentation is no longer being updated. -We recommend instead to use {esf-ref}[{esf}] to ships logs from your AWS environment to Elastic. - -{beatname_uc} is an Elastic https://www.elastic.co/beats[Beat] that you -deploy as a function in your serverless environment to collect data from cloud -services and ship it to the {stack}. - -Version {version} supports deploying {beatname_uc} as an AWS Lambda service. It -responds to triggers defined for the following event sources: - -* https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/WhatIsCloudWatchLogs.html[Amazon CloudWatch Logs] -* https://docs.aws.amazon.com/AWSSimpleQueueService/latest/SQSDeveloperGuide/welcome.html[Amazon Simple Queue Service (SQS)] -* https://docs.aws.amazon.com/kinesis/latest/APIReference/Welcome.html[Amazon Kinesis] - -image::./images/diagram-functionbeat-architecture.svg["{beatname_uc} collects events generated by cloud services"] - -include::{libbeat-dir}/shared-libbeat-description.asciidoc[] - -The following sections explore some common use cases for {beatname_uc}: - -* <> -* <> - -*Want to ship logs from Google Cloud?* Use our Google Cloud Dataflow templates -to ship Google Pub/Sub and Google Cloud Storage logs directly from the Google -Cloud Console. To learn more, refer to -{observability-guide}/gcp-dataflow.html[GCP Dataflow templates]. - -[float] -[[monitor-cloud-deployments]] -=== Monitor cloud deployments - -You can deploy {beatname_uc} on your serverless environment to collect logs and -metrics generated by cloud services and stream the data to the {stack} for -centralized analytics. - -[float] -==== Monitor AWS services with CloudWatch logs - -You can deploy {beatname_uc} as a Lambda function on AWS to receive events from -a Cloudwatch Log group, extract and structure the relevant fields, then stream -the events to {es}. - -The processing pipeline for this use case typically looks like this: - -. {beatname_uc} runs as a Lambda function on AWS and reads the data stream from -a Cloudwatch Log group. - -. {beats} processors, such as <> and <>, -filter and structure the events. - -. Optional {ref}/ingest.html[ingest pipelines] in {es} further enhance the -data. - -. The structured events are indexed into an {es} cluster. - -image::./images/functionbeat-pipeline-cloudwatchlogs.png["{beatname_uc} collects events generated by CloudWatch logs"] - -///// -The following is commented out until this architecture is fully enabled: -If you have multiple instances of CloudWatch logs and want to centralize your -logging environment in Amazon Kinesis, you can send the logs to Kinesis, then -use {beatname_uc} to receive events from Kinesis, process them, and then stream -them to {es} for further analysis. -///// - -[float] -[[event-drive-processing]] -=== Perform event-driven processing - -You can use {beatname_uc} to implement event-driven processing workflows with -cloud messaging queues and the {stack}. {beatname_uc} responds to event triggers -from AWS Kinesis and SQS. - -[float] -==== Analyze application data from SQS - -For applications that send JSON-encoded events to an SQS queue, {beatname_uc} -can listen for, ingest, and decode JSON events prior to -shipping them to {es}, where you can analyze the streaming data. - -The processing pipeline for this use case typically looks like this: - -. {beatname_uc} runs as a serverless shipper and listens to an SQS queue for -application events. - -. The {beats} <> processor -decodes JSON strings and replaces them with valid JSON objects. - -. Optional {ref}/ingest.html[ingest pipelines] in {es} further enhance the -data. - -. The events are indexed into an {es} cluster. - -image::./images/functionbeat-pipeline-sqs.png["{beatname_uc} application events triggered by SQS"] diff --git a/x-pack/functionbeat/docs/page_header.html b/x-pack/functionbeat/docs/page_header.html deleted file mode 100644 index 5c1aaf1ba115..000000000000 --- a/x-pack/functionbeat/docs/page_header.html +++ /dev/null @@ -1,3 +0,0 @@ -Functionbeat reached End of Support on October 18, 2023. You must consider -moving your deployments to the more versatile and efficient Elastic Serverless -Forwarder. diff --git a/x-pack/functionbeat/docs/setting-up-running.asciidoc b/x-pack/functionbeat/docs/setting-up-running.asciidoc deleted file mode 100644 index 823bbbd40672..000000000000 --- a/x-pack/functionbeat/docs/setting-up-running.asciidoc +++ /dev/null @@ -1,45 +0,0 @@ -///// -// NOTE: -// Each beat has its own setup overview to allow for the addition of content -// that is unique to each beat. -///// - -[[setting-up-and-running]] -[role="xpack"] -== Set up and deploy {beatname_uc} - -++++ -Set up and deploy -++++ - -Before reading this section, see -<<{beatname_lc}-installation-configuration>> for basic -installation instructions to get you started. - -This section includes additional information on how to install, set up, and run -{beatname_uc}, including: - -* <> - -* <> - -* <> - -* <> - -* <> - - -//MAINTAINERS: If you add a new file to this section, make sure you update the bulleted list ^^ too. - -[role="xpack"] -include::{libbeat-dir}/shared-directory-layout.asciidoc[] - -include::iam-permissions.asciidoc[] - -include::deploying.asciidoc[] - -[role="xpack"] -include::{libbeat-dir}/command-reference.asciidoc[] - -include::export-cloudformation-template.asciidoc[] diff --git a/x-pack/functionbeat/docs/tab-widgets/credentials-aws-widget.asciidoc b/x-pack/functionbeat/docs/tab-widgets/credentials-aws-widget.asciidoc deleted file mode 100644 index d1db7f99189d..000000000000 --- a/x-pack/functionbeat/docs/tab-widgets/credentials-aws-widget.asciidoc +++ /dev/null @@ -1,58 +0,0 @@ -++++ -

-
- - - -
-
-++++ - -include::credentials-aws.asciidoc[tag=mac] - -++++ -
- - -
-++++ diff --git a/x-pack/functionbeat/docs/tab-widgets/credentials-aws.asciidoc b/x-pack/functionbeat/docs/tab-widgets/credentials-aws.asciidoc deleted file mode 100644 index 16f330c906f4..000000000000 --- a/x-pack/functionbeat/docs/tab-widgets/credentials-aws.asciidoc +++ /dev/null @@ -1,26 +0,0 @@ -// tag::mac[] -[source, shell] ----- -export AWS_ACCESS_KEY_ID=ABCDEFGHIJKLMNOPUSER -export AWS_SECRET_ACCESS_KEY=EXAMPLE567890devgHIJKMLOPNQRSTUVZ1234KEY -export AWS_DEFAULT_REGION=us-east-1 ----- -// end::mac[] - -// tag::linux[] -[source, shell] ----- -export AWS_ACCESS_KEY_ID=ABCDEFGHIJKLMNOPUSER -export AWS_SECRET_ACCESS_KEY=EXAMPLE567890devgHIJKMLOPNQRSTUVZ1234KEY -export AWS_DEFAULT_REGION=us-east-1 ----- -// end::linux[] - -// tag::win[] -[source, shell] ----- -set AWS_ACCESS_KEY_ID=ABCDEFGHIJKLMNOPUSER -set AWS_SECRET_ACCESS_KEY=EXAMPLE567890devgHIJKMLOPNQRSTUVZ1234KEY -set AWS_DEFAULT_REGION=us-east-1 ----- -// end::win[] diff --git a/x-pack/functionbeat/docs/tab-widgets/deploy-aws-widget.asciidoc b/x-pack/functionbeat/docs/tab-widgets/deploy-aws-widget.asciidoc deleted file mode 100644 index a6575c0e8597..000000000000 --- a/x-pack/functionbeat/docs/tab-widgets/deploy-aws-widget.asciidoc +++ /dev/null @@ -1,58 +0,0 @@ -++++ -
-
- - - -
-
-++++ - -include::deploy-aws.asciidoc[tag=mac] - -++++ -
- - -
-++++ diff --git a/x-pack/functionbeat/docs/tab-widgets/deploy-aws.asciidoc b/x-pack/functionbeat/docs/tab-widgets/deploy-aws.asciidoc deleted file mode 100644 index 9118384d6e0b..000000000000 --- a/x-pack/functionbeat/docs/tab-widgets/deploy-aws.asciidoc +++ /dev/null @@ -1,19 +0,0 @@ -// tag::mac[] -["source","sh",subs="attributes"] ----- -./{beatname_lc} -v -e -d "*" deploy cloudwatch ----- -// end::mac[] - -// tag::linux[] -["source","sh",subs="attributes"] ----- -./{beatname_lc} -v -e -d "*" deploy cloudwatch ----- -// end::linux[] -// tag::win[] -["source","sh",subs="attributes"] ----- -.{backslash}{beatname_lc}.exe -v -e -d "*" deploy cloudwatch ----- -// end::win[] diff --git a/x-pack/functionbeat/docs/troubleshooting.asciidoc b/x-pack/functionbeat/docs/troubleshooting.asciidoc deleted file mode 100644 index 777f24edd82e..000000000000 --- a/x-pack/functionbeat/docs/troubleshooting.asciidoc +++ /dev/null @@ -1,43 +0,0 @@ -[[troubleshooting]] -[role="xpack"] -= Troubleshoot - -[partintro] --- -If you have issues installing or running {beatname_uc}, read the -following tips: - -* <> -* <> -* <> -* <> - -//sets block macro for getting-help.asciidoc included in next section - --- - -[[getting-help]] -[role="xpack"] -== Get help - -include::{libbeat-dir}/getting-help.asciidoc[] - -//sets block macro for debugging.asciidoc included in next section - -[id="enable-{beatname_lc}-debugging"] -[role="xpack"] -== Debug - -include::{libbeat-dir}/debugging.asciidoc[] - -//sets block macro for metrics-in-logs.asciidoc included in next section - -[id="understand-{beatname_lc}-logs"] -[role="xpack"] -== Understand metrics in {beatname_uc} logs - -++++ -Understand logged metrics -++++ - -include::{libbeat-dir}/metrics-in-logs.asciidoc[] diff --git a/x-pack/functionbeat/function/beater/functionbeat.go b/x-pack/functionbeat/function/beater/functionbeat.go deleted file mode 100644 index 77ea2a7bd008..000000000000 --- a/x-pack/functionbeat/function/beater/functionbeat.go +++ /dev/null @@ -1,185 +0,0 @@ -// Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one -// or more contributor license agreements. Licensed under the Elastic License; -// you may not use this file except in compliance with the Elastic License. - -package beater - -import ( - "context" - "fmt" - "os" - "strings" - "time" - - "github.com/elastic/beats/v7/libbeat/common/fmtstr" - "github.com/elastic/beats/v7/libbeat/outputs/elasticsearch" - "github.com/elastic/beats/v7/libbeat/publisher/pipeline" - "github.com/elastic/elastic-agent-libs/mapstr" - - "github.com/elastic/beats/v7/libbeat/beat" - "github.com/elastic/beats/v7/libbeat/licenser" - "github.com/elastic/beats/v7/libbeat/processors" - "github.com/elastic/beats/v7/x-pack/functionbeat/config" - "github.com/elastic/beats/v7/x-pack/functionbeat/function/core" - "github.com/elastic/beats/v7/x-pack/functionbeat/function/provider" - "github.com/elastic/beats/v7/x-pack/functionbeat/function/telemetry" - conf "github.com/elastic/elastic-agent-libs/config" - "github.com/elastic/elastic-agent-libs/logp" - "github.com/elastic/elastic-agent-libs/monitoring" -) - -var ( - graceDelay = 45 * time.Minute - refreshDelay = 15 * time.Minute - supportedOutputs = []string{ - "elasticsearch", - "logstash", - "console", // for local debugging - } -) - -// Functionbeat is a beat designed to run under a serverless environment and listen to external triggers, -// each invocation will generate one or more events to Elasticsearch. -// -// Each serverless implementation is different but functionbeat follows a few execution rules. -// - Publishing events from the source to the output is done synchronously. -// - Execution can be suspended. -// - Run on a read only filesystem -// - More execution constraints based on speed and memory usage. -type Functionbeat struct { - Ctx context.Context - log *logp.Logger - cancel context.CancelFunc - telemetry telemetry.T - Provider provider.Provider - Config *config.Config -} - -// New creates an instance of functionbeat. -func New(b *beat.Beat, cfg *conf.C) (beat.Beater, error) { - - c := &config.DefaultConfig - if err := cfg.Unpack(c); err != nil { - return nil, fmt.Errorf("error reading config file: %+v", err) - } - - provider, err := provider.Create(c.Provider) - if err != nil { - return nil, err - } - ctx, cancel := context.WithCancel(context.Background()) - - telemetryReg := monitoring.GetNamespace("state").GetRegistry().NewRegistry("functionbeat") - - bt := &Functionbeat{ - Ctx: ctx, - log: logp.NewLogger("functionbeat"), - cancel: cancel, - telemetry: telemetry.New(telemetryReg), - Provider: provider, - Config: c, - } - return bt, nil -} - -// Run starts functionbeat. -func (bt *Functionbeat) Run(b *beat.Beat) error { - defer bt.cancel() - - outputName := b.Config.Output.Name() - if !isOutputSupported(outputName) { - return fmt.Errorf("unsupported output type: %s; supported ones: %+v", outputName, supportedOutputs) - } - - elasticsearch.RegisterGlobalCallback(licenser.FetchAndVerify) - - bt.log.Info("Functionbeat is running") - defer bt.log.Info("Functionbeat stopped running") - - clientFactory := makeClientFactory(bt.log, b.Publisher, b.Info) - - enabledFunctions := bt.enabledFunctions() - bt.log.Infof("Functionbeat is configuring enabled functions: %s", strings.Join(enabledFunctions, ", ")) - // Create a client per function and wrap them into a runnable function by the coordinator. - functions, err := bt.Provider.CreateFunctions(clientFactory, enabledFunctions) - if err != nil { - return fmt.Errorf("error when creating the functions, error: %+v", err) - } - - // manages the goroutine related to the function handlers, if an error occurs and its not handled - // by the function itself, it will reach the coordinator, we log the error and shutdown beats. - // When an error reach the coordinator we assume that we cannot recover from it and we initiate - // a shutdown and return an aggregated errors. - coordinator := core.NewCoordinator(logp.NewLogger("coordinator"), functions...) - err = coordinator.Run(bt.Ctx, bt.telemetry) - if err != nil { - return err - } - return nil -} - -// enabledFunctions returns the enabled function types -func (bt *Functionbeat) enabledFunctions() (values []string) { - raw, found := os.LookupEnv("ENABLED_FUNCTIONS") - if !found { - return values - } - return strings.Split(raw, ",") -} - -// Stop stops functionbeat. -func (bt *Functionbeat) Stop() { - bt.log.Info("Functionbeat is stopping") - defer bt.log.Info("Functionbeat is stopped") - bt.cancel() -} - -func isOutputSupported(name string) bool { - for _, output := range supportedOutputs { - if name == output { - return true - } - } - return false -} - -type fnExtraConfig struct { - Processors processors.PluginConfig `config:"processors"` - - // KeepNull determines whether published events will keep null values or omit them. - KeepNull bool `config:"keep_null"` - - mapstr.EventMetadata `config:",inline"` // Fields and tags to add to events. - - // ES output index pattern - Index fmtstr.EventFormatString `config:"index"` -} - -func makeClientFactory(log *logp.Logger, pipe beat.Pipeline, beatInfo beat.Info) func(*conf.C) (pipeline.ISyncClient, error) { - // Each function has his own client to the publisher pipeline, - // publish operation will block the calling thread, when the method unwrap we have received the - // ACK for the batch. - return func(cfg *conf.C) (pipeline.ISyncClient, error) { - c := fnExtraConfig{} - - if err := cfg.Unpack(&c); err != nil { - return nil, err - } - - funcProcessors, err := processorsForFunction(beatInfo, c) - if err != nil { - return nil, err - } - - client, err := pipeline.NewSyncClient(log, pipe, beat.ClientConfig{ - PublishMode: beat.GuaranteedSend, - Processing: beat.ProcessingConfig{ - Processor: funcProcessors, - EventMetadata: c.EventMetadata, - KeepNull: c.KeepNull, - }, - }) - - return client, err - } -} diff --git a/x-pack/functionbeat/function/beater/proccessors_test.go b/x-pack/functionbeat/function/beater/proccessors_test.go deleted file mode 100644 index d15f5320e40d..000000000000 --- a/x-pack/functionbeat/function/beater/proccessors_test.go +++ /dev/null @@ -1,124 +0,0 @@ -// Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one -// or more contributor license agreements. Licensed under the Elastic License; -// you may not use this file except in compliance with the Elastic License. - -package beater - -import ( - "testing" - "time" - - "github.com/stretchr/testify/assert" - - "github.com/elastic/beats/v7/libbeat/beat" - _ "github.com/elastic/beats/v7/libbeat/processors/actions" - conf "github.com/elastic/elastic-agent-libs/config" - "github.com/elastic/elastic-agent-libs/mapstr" -) - -func TestProcessorsForFunction(t *testing.T) { - testCases := map[string]struct { - beatInfo beat.Info - configStr string - event beat.Event - expectedFields map[string]string - }{ - "Simple static index": { - configStr: "index: 'test'", - expectedFields: map[string]string{ - "@metadata.raw_index": "test", - }, - }, - "Index with agent info + timestamp": { - beatInfo: beat.Info{Beat: "TestBeat", Version: "3.9.27"}, - configStr: "index: 'beat-%{[agent.name]}-%{[agent.version]}-%{+yyyy.MM.dd}'", - event: beat.Event{Timestamp: time.Date(1999, time.December, 31, 23, 0, 0, 0, time.UTC)}, - expectedFields: map[string]string{ - "@metadata.raw_index": "beat-TestBeat-3.9.27-1999.12.31", - }, - }, - "Set field in input config": { - configStr: `processors: [add_fields: {fields: {testField: inputConfig}}]`, - expectedFields: map[string]string{ - "fields.testField": "inputConfig", - }, - }, - } - for description, test := range testCases { - if test.event.Fields == nil { - test.event.Fields = mapstr.M{} - } - config, err := functionConfigFromString(test.configStr) - if err != nil { - t.Errorf("[%s] %v", description, err) - continue - } - processors, err := processorsForFunction(test.beatInfo, config) - if err != nil { - t.Errorf("[%s] %v", description, err) - continue - } - processedEvent, err := processors.Run(&test.event) - // We don't check if err != nil, because we are testing the final outcome - // of running the processors, including when some of them fail. - if processedEvent == nil { - t.Errorf("[%s] Unexpected fatal error running processors: %v\n", - description, err) - } - for key, value := range test.expectedFields { - field, err := processedEvent.GetValue(key) - if err != nil { - t.Errorf("[%s] Couldn't get field %s from event: %v", description, key, err) - continue - } - assert.Equal(t, field, value) - fieldStr, ok := field.(string) - if !ok { - // Note that requiring a string here is just to simplify the test setup, - // not a requirement of the underlying api. - t.Errorf("[%s] Field [%s] should be a string", description, key) - continue - } - if fieldStr != value { - t.Errorf("[%s] Event field [%s]: expected [%s], got [%s]", description, key, value, fieldStr) - } - } - } -} - -func TestProcessorsForFunctionIsFlat(t *testing.T) { - // This test is regrettable, and exists because of inconsistencies in - // processor handling between processors.Processors and processing.group - // (which implements beat.ProcessorList) -- see processorsForConfig for - // details. The upshot is that, for now, if the function configuration specifies - // processors, they must be returned as direct children of the resulting - // processors.Processors (rather than being collected in additional tree - // structure). - // This test should be removed once we have a more consistent mechanism for - // collecting and running processors. - configStr := `processors: -- add_fields: {fields: {testField: value}} -- add_fields: {fields: {testField2: stuff}}` - config, err := functionConfigFromString(configStr) - if err != nil { - t.Fatal(err) - } - processors, err := processorsForFunction( - beat.Info{}, config) - if err != nil { - t.Fatal(err) - } - assert.Equal(t, 2, len(processors.List)) -} - -// Helper function to convert from YML input string to an unpacked -// fnExtraConfig -func functionConfigFromString(s string) (fnExtraConfig, error) { - config := fnExtraConfig{} - cfg, err := conf.NewConfigFrom(s) - if err != nil { - return config, err - } - err = cfg.Unpack(&config) - return config, err -} diff --git a/x-pack/functionbeat/function/beater/processors.go b/x-pack/functionbeat/function/beater/processors.go deleted file mode 100644 index 23c5da9ca232..000000000000 --- a/x-pack/functionbeat/function/beater/processors.go +++ /dev/null @@ -1,38 +0,0 @@ -// Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one -// or more contributor license agreements. Licensed under the Elastic License; -// you may not use this file except in compliance with the Elastic License. - -package beater - -import ( - "github.com/elastic/beats/v7/libbeat/beat" - "github.com/elastic/beats/v7/libbeat/common/fmtstr" - "github.com/elastic/beats/v7/libbeat/processors" - "github.com/elastic/beats/v7/libbeat/processors/add_formatted_index" -) - -func processorsForFunction(beatInfo beat.Info, config fnExtraConfig) (*processors.Processors, error) { - procs := processors.NewList(nil) - - // Processor ordering is important: - // 1. Index configuration - if !config.Index.IsEmpty() { - staticFields := fmtstr.FieldsForBeat(beatInfo.Beat, beatInfo.Version) - timestampFormat, err := - fmtstr.NewTimestampFormatString(&config.Index, staticFields) - if err != nil { - return nil, err - } - indexProcessor := add_formatted_index.New(timestampFormat) - procs.AddProcessor(indexProcessor) - } - - // 2. User processors - userProcessors, err := processors.New(config.Processors) - if err != nil { - return nil, err - } - procs.AddProcessors(*userProcessors) - - return procs, nil -} diff --git a/x-pack/functionbeat/function/cmd/root.go b/x-pack/functionbeat/function/cmd/root.go deleted file mode 100644 index 75206efbb2c2..000000000000 --- a/x-pack/functionbeat/function/cmd/root.go +++ /dev/null @@ -1,54 +0,0 @@ -// Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one -// or more contributor license agreements. Licensed under the Elastic License; -// you may not use this file except in compliance with the Elastic License. - -package cmd - -import ( - "fmt" - "os" - - "github.com/spf13/cobra" - - "github.com/elastic/beats/v7/libbeat/beat" - "github.com/elastic/beats/v7/libbeat/cfgfile" - "github.com/elastic/beats/v7/libbeat/cmd" - "github.com/elastic/beats/v7/libbeat/cmd/instance" - "github.com/elastic/beats/v7/x-pack/functionbeat/config" -) - -// FunctionCmd is the command of the function. -type FunctionCmd struct { - *cobra.Command - VersionCmd *cobra.Command -} - -// NewFunctionCmd return a new initialized function command. -func NewFunctionCmd(name string, beatCreator beat.Creator) *FunctionCmd { - settings := instance.Settings{ - Name: name, - IndexPrefix: name, - ConfigOverrides: config.FunctionOverrides, - } - - err := cfgfile.ChangeDefaultCfgfileFlag(settings.Name) - if err != nil { - panic(fmt.Errorf("failed to set default config file path: %v", err)) - } - - rootCmd := &FunctionCmd{ - &cobra.Command{ - Run: func(cmd *cobra.Command, args []string) { - err := instance.Run(settings, beatCreator) - if err != nil { - os.Exit(1) - } - }, - }, - cmd.GenVersionCmd(settings), - } - - rootCmd.AddCommand(rootCmd.VersionCmd) - - return rootCmd -} diff --git a/x-pack/functionbeat/function/core/coordinator.go b/x-pack/functionbeat/function/core/coordinator.go deleted file mode 100644 index b7cf2e716bec..000000000000 --- a/x-pack/functionbeat/function/core/coordinator.go +++ /dev/null @@ -1,98 +0,0 @@ -// Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one -// or more contributor license agreements. Licensed under the Elastic License; -// you may not use this file except in compliance with the Elastic License. - -package core - -import ( - "context" - "fmt" - - "github.com/joeshaw/multierror" - - "github.com/elastic/beats/v7/x-pack/functionbeat/function/telemetry" - "github.com/elastic/elastic-agent-libs/logp" -) - -// Runner is the interface that the coordinator will follow to manage a function goroutine. -type Runner interface { - fmt.Stringer - Run(context.Context, telemetry.T) error -} - -// Coordinator takes care of managing the function goroutine, it receives the list of functions that -// need to be executed and manage the goroutine. If an error happen and its not handled by the -// function, we assume its a fatal error and we will -// stop all the other goroutine and functionbeat will terminate. -type Coordinator struct { - log *logp.Logger - runners []Runner -} - -// NewCoordinator create a new coordinator objects receiving the clientFactory and the runner. -func NewCoordinator(log *logp.Logger, - runners ...Runner, -) *Coordinator { - if log == nil { - log = logp.NewLogger("") - } - log = log.Named("Coordinator") - return &Coordinator{log: log, runners: runners} -} - -// Run starts each functions into an independent goroutine and wait until all the goroutine are -// stopped to exit. -func (r *Coordinator) Run(ctx context.Context, t telemetry.T) error { - r.log.Debug("Coordinator is starting") - defer r.log.Debug("Coordinator is stopped") - - // When an errors happen in a function and its not handled by the running function, we log an error - // and we trigger a shutdown of all the others goroutine. - ctx, cancel := context.WithCancel(ctx) - defer cancel() - - results := make(chan error) - defer close(results) - - r.log.Debugf("The coordinator is starting %d functions", len(r.runners)) - for _, rfn := range r.runners { - go func(ctx context.Context, t telemetry.T, rfn Runner) { - var err error - defer func() { results <- err }() - err = r.runFunc(ctx, t, rfn) - if err != nil { - cancel() - } - }(ctx, t, rfn) - } - - // Wait for goroutine to complete and aggregate any errors from the goroutine and - // raise them back to the main program. - var errors multierror.Errors - for range r.runners { - err := <-results - if err != nil { - errors = append(errors, err) - } - } - return errors.Err() -} - -func (r *Coordinator) runFunc( - ctx context.Context, - t telemetry.T, - rfn Runner, -) error { - r.log.Infof("The function '%s' is starting", rfn.String()) - defer r.log.Infof("The function '%s' is stopped", rfn.String()) - - err := rfn.Run(ctx, t) - if err != nil { - r.log.Errorf( - "Nonrecoverable error when executing the function: '%s', error: '%+v', terminating all running functions", - rfn, - err, - ) - } - return err -} diff --git a/x-pack/functionbeat/function/core/coordinator_test.go b/x-pack/functionbeat/function/core/coordinator_test.go deleted file mode 100644 index 71f3356941d7..000000000000 --- a/x-pack/functionbeat/function/core/coordinator_test.go +++ /dev/null @@ -1,58 +0,0 @@ -// Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one -// or more contributor license agreements. Licensed under the Elastic License; -// you may not use this file except in compliance with the Elastic License. - -package core - -import ( - "context" - "errors" - "testing" - - "github.com/stretchr/testify/assert" - - "github.com/elastic/beats/v7/x-pack/functionbeat/function/telemetry" -) - -var errUnhappy = errors.New("unhappy :(") - -type happyRunner struct{} - -func (hr *happyRunner) Run(ctx context.Context, _ telemetry.T) error { - <-ctx.Done() - return nil -} -func (hr *happyRunner) String() string { return "happyRunner" } - -type unhappyRunner struct{} - -func (uhr *unhappyRunner) Run(ctx context.Context, _ telemetry.T) error { - return errUnhappy -} - -func (uhr *unhappyRunner) String() string { return "unhappyRunner" } - -func TestStart(t *testing.T) { - t.Run("start the runner", func(t *testing.T) { - coordinator := NewCoordinator(nil, &happyRunner{}, &happyRunner{}) - ctx, cancel := context.WithCancel(context.Background()) - var err error - go func() { - err = coordinator.Run(ctx, telemetry.Ignored()) - assert.NoError(t, err) - }() - cancel() - }) - - t.Run("on error shutdown all the runner", func(t *testing.T) { - coordinator := NewCoordinator(nil, &happyRunner{}, &unhappyRunner{}) - err := coordinator.Run(context.Background(), telemetry.Ignored()) - assert.Error(t, err) - }) - - t.Run("aggregate all errors", func(t *testing.T) { - coordinator := NewCoordinator(nil, &unhappyRunner{}, &unhappyRunner{}) - err := coordinator.Run(context.Background(), telemetry.Ignored()) - assert.Error(t, err) - }) -} diff --git a/x-pack/functionbeat/function/provider/cli.go b/x-pack/functionbeat/function/provider/cli.go deleted file mode 100644 index 7f112330289a..000000000000 --- a/x-pack/functionbeat/function/provider/cli.go +++ /dev/null @@ -1,32 +0,0 @@ -// Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one -// or more contributor license agreements. Licensed under the Elastic License; -// you may not use this file except in compliance with the Elastic License. - -package provider - -import ( - conf "github.com/elastic/elastic-agent-libs/config" - "github.com/elastic/elastic-agent-libs/logp" -) - -// CLIManager is the interface implemented by each provider to expose a command CLI interface -// to their interface. -type CLIManager interface { - // Deploy takes a function name and deploy functionbeat and the function configuration to the provider. - Deploy(string) error - - //Update takes a function name and update the configuration to the remote provider. - Update(string) error - - // Remove takes a function name and remove the specific function from the remote provider. - Remove(string) error - - // Export prints exported function template to stdout. - Export(string) error - - // Package packages functions for the provider configurable output. - Package(string) error -} - -// CLIManagerFactory factory method to call to create a new CLI manager -type CLIManagerFactory func(*logp.Logger, *conf.C, Provider) (CLIManager, error) diff --git a/x-pack/functionbeat/function/provider/default_provider.go b/x-pack/functionbeat/function/provider/default_provider.go deleted file mode 100644 index 3693d0a718f8..000000000000 --- a/x-pack/functionbeat/function/provider/default_provider.go +++ /dev/null @@ -1,112 +0,0 @@ -// Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one -// or more contributor license agreements. Licensed under the Elastic License; -// you may not use this file except in compliance with the Elastic License. - -package provider - -import ( - "fmt" - - "github.com/elastic/beats/v7/x-pack/functionbeat/config" - "github.com/elastic/beats/v7/x-pack/functionbeat/function/core" - conf "github.com/elastic/elastic-agent-libs/config" - "github.com/elastic/elastic-agent-libs/logp" -) - -// DefaultProvider implements the minimal required to retrieve and start functions. -type DefaultProvider struct { - rawConfig *conf.C - config *config.ProviderConfig - registry *Registry - name string - log *logp.Logger - managerFactory CLIManagerFactory - templateFactory TemplateBuilderFactory -} - -// NewDefaultProvider returns factory methods to handle generic provider. -func NewDefaultProvider( - name string, - manager CLIManagerFactory, - templater TemplateBuilderFactory, -) func(*logp.Logger, *Registry, *conf.C) (Provider, error) { - return func(log *logp.Logger, registry *Registry, cfg *conf.C) (Provider, error) { - c := &config.ProviderConfig{} - err := cfg.Unpack(c) - if err != nil { - return nil, err - } - - if manager == nil { - manager = NewNullCli - } - - return &DefaultProvider{ - rawConfig: cfg, - config: c, - registry: registry, - name: name, - log: log, - managerFactory: manager, - templateFactory: templater, - }, nil - } -} - -// Name returns the name of the provider. -func (d *DefaultProvider) Name() string { - return d.name -} - -// CreateFunctions takes factory method and returns runnable function. -func (d *DefaultProvider) CreateFunctions(clientFactory clientFactory, enabledFunctions []string) ([]core.Runner, error) { - return CreateFunctions(d.registry, d, enabledFunctions, d.config.Functions, clientFactory) -} - -// FindFunctionByName returns a function instance identified by a unique name or an error if not found. -func (d *DefaultProvider) FindFunctionByName(name string) (Function, error) { - return FindFunctionByName(d.registry, d, d.config.Functions, name) -} - -// CLIManager returns the type responsable of installing, updating and removing remote function -// for a specific provider. -func (d *DefaultProvider) CLIManager() (CLIManager, error) { - return d.managerFactory(nil, d.rawConfig, d) -} - -// TemplateBuilder returns a TemplateBuilder returns a the type responsible to generate templates. -func (d *DefaultProvider) TemplateBuilder() (TemplateBuilder, error) { - return d.templateFactory(d.log, d.rawConfig, d) -} - -// EnabledFunctions return the list of enabled funcionts. -func (d *DefaultProvider) EnabledFunctions() ([]string, error) { - return EnabledFunctions(d.registry, d, d.config.Functions) -} - -// nullCLI is used when a provider doesn't implement the CLI to manager functions on the service provider. -type nullCLI struct{} - -// NewNullCli returns a NOOP CliManager. -func NewNullCli(_ *logp.Logger, _ *conf.C, _ Provider) (CLIManager, error) { - return (*nullCLI)(nil), nil -} - -func (*nullCLI) Deploy(_ string) error { return fmt.Errorf("deploy not implemented") } -func (*nullCLI) Update(_ string) error { return fmt.Errorf("update not implemented") } -func (*nullCLI) Remove(_ string) error { return fmt.Errorf("remove not implemented") } -func (*nullCLI) Export(_ string) error { return fmt.Errorf("export not implemented") } -func (*nullCLI) Package(_ string) error { return fmt.Errorf("package not implemented") } - -// nullTemplateBuilder is used when a provider does not implement a template builder functionality. -type nullTemplateBuilder struct{} - -// NewNullTemplateBuilder returns a NOOP TemplateBuilder. -func NewNullTemplateBuilder(_ *logp.Logger, _ *conf.C, _ Provider) (TemplateBuilder, error) { - return (*nullTemplateBuilder)(nil), nil -} - -// RawTemplate returns a empty string. -func (*nullTemplateBuilder) RawTemplate(_ string) (string, error) { - return "", fmt.Errorf("raw temaplate not implemented") -} diff --git a/x-pack/functionbeat/function/provider/feature.go b/x-pack/functionbeat/function/provider/feature.go deleted file mode 100644 index 34c381b24714..000000000000 --- a/x-pack/functionbeat/function/provider/feature.go +++ /dev/null @@ -1,64 +0,0 @@ -// Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one -// or more contributor license agreements. Licensed under the Elastic License; -// you may not use this file except in compliance with the Elastic License. - -package provider - -import ( - "github.com/elastic/beats/v7/libbeat/feature" -) - -// getNamespace return the namespace for functions of a specific provider. The registry have a flat view -// representation of the plugin world this mean we don't really have a tree, instead what we do is -// to create a unique keys per providers that will only keep the functions of the provider. -func getNamespace(provider string) string { - return namespace + "." + provider + ".functions" -} - -// newFeature creates a new Provider feature to be added to the global registry. -// The namespace will be 'functionbeat.provider' in the registry. -func newFeature(name string, factory Factory) *feature.Feature { - return feature.New(namespace, name, factory) -} - -// newFunctionFeature Feature creates a new function feature to be added to the global registry -// The namespace will be 'functionbeat.provider.local' in the registry. -func newFunctionFeature( - provider, name string, - factory FunctionFactory, -) *feature.Feature { - return feature.New(getNamespace(provider), name, factory) -} - -// builder is used to have a fluent interface to build a set of function for a specific provider, it -// provides a fluent interface to the developper of provider and functions, it wraps the Feature -// functions to make sure the namespace are correctly configured. -type builder struct { - name string - features []feature.Featurable -} - -// Builder creates a new provider builder, it is used to define a provider and the function -// it supports. -func Builder(name string, factory Factory, details feature.Details) *builder { - return &builder{ - name: name, - features: []feature.Featurable{ - newFeature(name, factory), - }, - } -} - -func (b *builder) Features() []feature.Featurable { - return b.features -} - -// AddFunction adds a new function type to the provider and return the builder. -func (b *builder) AddFunction( - name string, - factory FunctionFactory, - details feature.Details, -) *builder { - b.features = append(b.features, newFunctionFeature(b.name, name, factory)) - return b -} diff --git a/x-pack/functionbeat/function/provider/feature_test.go b/x-pack/functionbeat/function/provider/feature_test.go deleted file mode 100644 index a0b8a6d7fcbe..000000000000 --- a/x-pack/functionbeat/function/provider/feature_test.go +++ /dev/null @@ -1,51 +0,0 @@ -// Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one -// or more contributor license agreements. Licensed under the Elastic License; -// you may not use this file except in compliance with the Elastic License. - -package provider - -import ( - "testing" - - "github.com/stretchr/testify/assert" - "github.com/stretchr/testify/require" - - "github.com/elastic/beats/v7/libbeat/feature" - conf "github.com/elastic/elastic-agent-libs/config" - "github.com/elastic/elastic-agent-libs/logp" -) - -func TestBuilder(t *testing.T) { - provider := "myprovider" - providerFactory := func(_ *logp.Logger, _ *Registry, _ *conf.C) (Provider, error) { - return nil, nil - } - - fnFactory1 := func(_ Provider, _ *conf.C) (Function, error) { return nil, nil } - fnFactory2 := func(_ Provider, _ *conf.C) (Function, error) { return nil, nil } - - features := Builder( - provider, - providerFactory, - feature.MakeDetails("myprovider", "myprovider", feature.Experimental), - ).AddFunction( - "f1", - fnFactory1, - feature.MakeDetails("fn1 description", "fn1", feature.Experimental), - ).AddFunction("f2", fnFactory2, feature.MakeDetails( - "fn1 description", - "fn1", - feature.Experimental, - )).Features() - - require.Equal(t, 3, len(features)) - - assert.Equal(t, "myprovider", features[0].Name()) - assert.Equal(t, "functionbeat.provider", features[0].Namespace()) - - assert.Equal(t, "f1", features[1].Name()) - assert.Equal(t, "functionbeat.provider.myprovider.functions", features[1].Namespace()) - - assert.Equal(t, "f2", features[2].Name()) - assert.Equal(t, "functionbeat.provider.myprovider.functions", features[2].Namespace()) -} diff --git a/x-pack/functionbeat/function/provider/provider.go b/x-pack/functionbeat/function/provider/provider.go deleted file mode 100644 index 6c33eb80b1a1..000000000000 --- a/x-pack/functionbeat/function/provider/provider.go +++ /dev/null @@ -1,133 +0,0 @@ -// Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one -// or more contributor license agreements. Licensed under the Elastic License; -// you may not use this file except in compliance with the Elastic License. - -package provider - -import ( - "context" - "fmt" - - "github.com/elastic/beats/v7/libbeat/feature" - "github.com/elastic/beats/v7/libbeat/publisher/pipeline" - "github.com/elastic/beats/v7/x-pack/functionbeat/function/core" - "github.com/elastic/beats/v7/x-pack/functionbeat/function/telemetry" - conf "github.com/elastic/elastic-agent-libs/config" - "github.com/elastic/elastic-agent-libs/logp" -) - -// Create a new pipeline client based on the function configuration. -type clientFactory func(*conf.C) (pipeline.ISyncClient, error) - -// Function is temporary -type Function interface { - Run(context.Context, pipeline.ISyncClient, telemetry.T) error - Name() string -} - -// Provider providers the layer between functionbeat and cloud specific settings, its is responsable to -// return the function that need to be executed. -type Provider interface { - CreateFunctions(clientFactory, []string) ([]core.Runner, error) - FindFunctionByName(string) (Function, error) - EnabledFunctions() ([]string, error) - CLIManager() (CLIManager, error) - TemplateBuilder() (TemplateBuilder, error) - Name() string -} - -// Runnable is the unit of work managed by the coordinator, anything related to the life of a function -// is encapsulated into the runnable. -type Runnable struct { - config *conf.C - function Function - makeClient clientFactory -} - -// Run call the the function's Run method, the method is a specific goroutine, it will block until -// beats shutdown or an error happen. -func (r *Runnable) Run(ctx context.Context, t telemetry.T) error { - client, err := r.makeClient(r.config) - if err != nil { - return fmt.Errorf("could not create a client for the function: %w", err) - } - defer client.Close() - return r.function.Run(ctx, client, t) -} - -func (r *Runnable) String() string { - return r.function.Name() -} - -// NewProvider return the provider specified in the configuration or an error. -func NewProvider(name string, cfg *conf.C) (Provider, error) { - // Configure the provider, the provider will take care of the configuration for the - // functions. - registry := NewRegistry(feature.GlobalRegistry()) - providerFunc, err := registry.Lookup(name) - if err != nil { - return nil, fmt.Errorf("error finding the provider '%s', error: %v", name, err) - } - - provider, err := providerFunc(logp.NewLogger("provider"), registry, cfg) - if err != nil { - return nil, fmt.Errorf("error creating the provider '%s', error: %v", name, err) - } - - return provider, nil -} - -// IsAvailable checks if a cloud provider is available in the binary. -func IsAvailable(name string) (bool, error) { - registry := NewRegistry(feature.GlobalRegistry()) - - availableProviders, err := registry.AvailableProviders() - if err != nil { - return false, err - } - - for _, p := range availableProviders { - if p == name { - return true, nil - } - } - return false, nil -} - -// ListFunctions returns the list of enabled function names. -func ListFunctions(provider string) ([]string, error) { - functions, err := feature.GlobalRegistry().LookupAll(getNamespace(provider)) - if err != nil { - return nil, err - } - - names := make([]string, len(functions)) - for i, f := range functions { - names[i] = f.Name() - } - return names, nil -} - -// Create returns the provider from a configuration. -func Create(cfg *conf.C) (Provider, error) { - providers, err := List() - if err != nil { - return nil, err - } - if len(providers) != 1 { - return nil, fmt.Errorf("too many providers are available, expected one, got: %s", providers) - } - - providerCfg, err := cfg.Child(providers[0], -1) - if err != nil { - return nil, err - } - - return NewProvider(providers[0], providerCfg) -} - -// List returns the list of available providers. -func List() ([]string, error) { - registry := NewRegistry(feature.GlobalRegistry()) - return registry.AvailableProviders() -} diff --git a/x-pack/functionbeat/function/provider/provider_test.go b/x-pack/functionbeat/function/provider/provider_test.go deleted file mode 100644 index 47385cbb0292..000000000000 --- a/x-pack/functionbeat/function/provider/provider_test.go +++ /dev/null @@ -1,74 +0,0 @@ -// Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one -// or more contributor license agreements. Licensed under the Elastic License; -// you may not use this file except in compliance with the Elastic License. - -package provider - -import ( - "context" - "errors" - "testing" - - "github.com/stretchr/testify/assert" - - "github.com/elastic/beats/v7/libbeat/beat" - "github.com/elastic/beats/v7/libbeat/publisher/pipeline" - "github.com/elastic/beats/v7/x-pack/functionbeat/function/telemetry" - conf "github.com/elastic/elastic-agent-libs/config" -) - -type simpleFunction struct { - err error -} - -func (s *simpleFunction) Run(ctx context.Context, client pipeline.ISyncClient, _ telemetry.T) error { - return s.err -} - -func (s *simpleFunction) Name() string { - return "simpleFunction" -} - -type mockClient struct{} - -func (sc *mockClient) Publish(event beat.Event) error { return nil } -func (sc *mockClient) PublishAll(events []beat.Event) error { return nil } -func (sc *mockClient) Close() error { return nil } -func (sc *mockClient) Wait() {} - -func TestRunnable(t *testing.T) { - t.Run("return an error when we cannot create the client", func(t *testing.T) { - err := errors.New("oops") - runnable := Runnable{ - config: conf.NewConfig(), - makeClient: func(cfg *conf.C) (pipeline.ISyncClient, error) { return nil, err }, - function: &simpleFunction{err: nil}, - } - - errReceived := runnable.Run(context.Background(), telemetry.Ignored()) - assert.Equal(t, "could not create a client for the function: "+err.Error(), errReceived.Error()) - }) - - t.Run("propagate functions errors to the coordinator", func(t *testing.T) { - err := errors.New("function error") - runnable := Runnable{ - config: conf.NewConfig(), - makeClient: func(cfg *conf.C) (pipeline.ISyncClient, error) { return &mockClient{}, nil }, - function: &simpleFunction{err: err}, - } - - errReceived := runnable.Run(context.Background(), telemetry.Ignored()) - assert.Equal(t, err.Error(), errReceived.Error()) - }) - - t.Run("when there is no error run and exit normaly", func(t *testing.T) { - runnable := Runnable{ - config: conf.NewConfig(), - makeClient: func(cfg *conf.C) (pipeline.ISyncClient, error) { return &mockClient{}, nil }, - function: &simpleFunction{err: nil}, - } - - errReceived := runnable.Run(context.Background(), telemetry.Ignored()) - assert.NoError(t, errReceived) - }) -} diff --git a/x-pack/functionbeat/function/provider/registry.go b/x-pack/functionbeat/function/provider/registry.go deleted file mode 100644 index 4cd1575cac0c..000000000000 --- a/x-pack/functionbeat/function/provider/registry.go +++ /dev/null @@ -1,217 +0,0 @@ -// Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one -// or more contributor license agreements. Licensed under the Elastic License; -// you may not use this file except in compliance with the Elastic License. - -package provider - -import ( - "errors" - "fmt" - - "github.com/elastic/beats/v7/libbeat/feature" - "github.com/elastic/beats/v7/x-pack/functionbeat/config" - "github.com/elastic/beats/v7/x-pack/functionbeat/function/core" - conf "github.com/elastic/elastic-agent-libs/config" - "github.com/elastic/elastic-agent-libs/logp" -) - -// Errors generated by the registry when we are retrieving providers or functions from the main registry. -var ( - errInvalidProvider = errors.New("invalid provider name") - errInvalidFunctionName = errors.New("invalid function name") - errInvalidType = errors.New("incomptible type received for the feature") -) - -// namespace is the namespace were providers will be registered in the global registry. -const namespace = "functionbeat.provider" - -// Factory factory to create a concrete provider for a specific cloud service. -type Factory func(*logp.Logger, *Registry, *conf.C) (Provider, error) - -// FunctionFactory factory to create a concrete function. -type FunctionFactory func(Provider, *conf.C) (Function, error) - -// Registry is a wrapper around the global feature registry and will take care of returning the -// the right providers and will do the type assertion for the providers, we hide the fact that -// we are actually accessing a global registry. -type Registry struct { - registry *feature.Registry -} - -// NewRegistry return a new registry. -func NewRegistry(registry *feature.Registry) *Registry { - return &Registry{registry: registry} -} - -// Lookup search the registry for the specific provider, normalization is done inside the -// registry to deal with lower case and uppercase. -func (r *Registry) Lookup(name string) (Factory, error) { - if len(name) == 0 { - return nil, errInvalidProvider - } - - f, err := r.registry.Lookup(namespace, name) - if err != nil { - return nil, err - } - - p, ok := f.Factory().(Factory) - if !ok { - return nil, errInvalidType - } - - return p, nil -} - -// LookupFunction takes a provider and a function and return the corresponding type or an -// error if the function or the provider is not found. -func (r *Registry) LookupFunction(provider, function string) (FunctionFactory, error) { - if len(provider) == 0 { - return nil, errInvalidProvider - } - if len(function) == 0 { - return nil, errInvalidFunctionName - } - - if _, err := r.Lookup(provider); err != nil { - return nil, err - } - - ns := getNamespace(provider) - - f, err := r.registry.Lookup(ns, function) - if err != nil { - return nil, err - } - - fn, ok := f.Factory().(FunctionFactory) - if !ok { - return nil, errInvalidType - } - - return fn, nil -} - -// AvailableProviders returns the names of registered providers. -func (r *Registry) AvailableProviders() ([]string, error) { - providerFeatures, err := r.registry.LookupAll(namespace) - if err != nil { - return nil, err - } - - var providers []string - for _, f := range providerFeatures { - providers = append(providers, f.Name()) - } - - return providers, nil -} - -// CreateFunctions create runnable function based on the configurations received. -func CreateFunctions( - registry *Registry, - provider Provider, - enabledFunctions []string, - configs []*conf.C, - clientFactory clientFactory, -) ([]core.Runner, error) { - var runners []core.Runner - - for _, cfg := range configs { - c := config.DefaultFunctionConfig - err := cfg.Unpack(&c) - if err != nil { - return nil, err - } - - if strInSlice(enabledFunctions, c.Name.String()) == -1 { - continue - } - - if !c.Enabled { - return nil, fmt.Errorf("function '%s' not enabled for provider '%s'", c.Name, provider.Name()) - } - - f, err := registry.LookupFunction(provider.Name(), c.Type) - if err != nil { - return nil, err - } - - fn, err := f(provider, cfg) - if err != nil { - return nil, err - } - - runners = append(runners, &Runnable{config: cfg, makeClient: clientFactory, function: fn}) - } - - if len(runners) == 0 { - return nil, fmt.Errorf("no function are enabled for selected provider: '%s'", provider.Name()) - } - return runners, nil -} - -func strInSlice(haystack []string, name string) int { - for idx, s := range haystack { - if s == name { - return idx - } - } - return -1 -} - -// FindFunctionByName returns a function instance identified by a unique name or an error if not found. -func FindFunctionByName( - registry *Registry, - provider Provider, - configs []*conf.C, - name string, -) (Function, error) { - - for _, cfg := range configs { - c := config.FunctionConfig{} - err := cfg.Unpack(&c) - if err != nil { - return nil, err - } - - if c.Name.String() != name { - continue - } - - if !c.Enabled { - return nil, fmt.Errorf("function '%s' not enabled for provider '%s'", name, provider.Name()) - } - - f, err := registry.LookupFunction(provider.Name(), c.Type) - if err != nil { - return nil, err - } - - fn, err := f(provider, cfg) - if err != nil { - return nil, err - } - return fn, nil - } - - return nil, fmt.Errorf("no function with name '%s' exists", name) -} - -// EnabledFunctions returns the list of enabled functions. -func EnabledFunctions(registry *Registry, provider Provider, configs []*conf.C) ([]string, error) { - var names []string - for _, cfg := range configs { - c := config.FunctionConfig{} - err := cfg.Unpack(&c) - if err != nil { - return names, fmt.Errorf("error while finding enabled functions: %+v", err) - } - - if c.Enabled { - names = append(names, c.Name.String()) - } - } - - return names, nil -} diff --git a/x-pack/functionbeat/function/provider/registry_test.go b/x-pack/functionbeat/function/provider/registry_test.go deleted file mode 100644 index 01c994c6186c..000000000000 --- a/x-pack/functionbeat/function/provider/registry_test.go +++ /dev/null @@ -1,274 +0,0 @@ -// Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one -// or more contributor license agreements. Licensed under the Elastic License; -// you may not use this file except in compliance with the Elastic License. - -package provider - -import ( - "context" - "errors" - "reflect" - "testing" - - "github.com/stretchr/testify/assert" - - "github.com/elastic/beats/v7/libbeat/feature" - "github.com/elastic/beats/v7/libbeat/publisher/pipeline" - "github.com/elastic/beats/v7/x-pack/functionbeat/function/core" - "github.com/elastic/beats/v7/x-pack/functionbeat/function/telemetry" - conf "github.com/elastic/elastic-agent-libs/config" - "github.com/elastic/elastic-agent-libs/logp" -) - -type mockProvider struct { - runners []core.Runner - name string -} - -func (m *mockProvider) CreateFunctions(clientFactory clientFactory, _ []string) ([]core.Runner, error) { - return m.runners, nil -} - -func (m *mockProvider) FindFunctionByName(_ string) (Function, error) { - return nil, errors.New("not found") -} - -func (m *mockProvider) Name() string { return m.name } - -func (m *mockProvider) CLIManager() (CLIManager, error) { return nil, nil } - -func (m *mockProvider) TemplateBuilder() (TemplateBuilder, error) { return nil, nil } - -func (m *mockProvider) EnabledFunctions() ([]string, error) { return []string{}, nil } - -func TestRegistry(t *testing.T) { - t.Run("provider", testProviderLookup) - t.Run("functions", testFunctionLookup) -} - -type mockFunction struct { - name string -} - -func (mf *mockFunction) Run(ctx context.Context, client pipeline.ISyncClient, t telemetry.T) error { - return nil -} -func (mf *mockFunction) Name() string { return mf.name } - -func testProviderLookup(t *testing.T) { - name := "myprovider" - myprovider := &mockProvider{} - - providerFn := func(log *logp.Logger, registry *Registry, config *conf.C) (Provider, error) { - return myprovider, nil - } - - f := newFeature( - name, - providerFn, - ) - - t.Run("adding and retrieving a provider", withRegistry(func( - t *testing.T, - global *feature.Registry, - wrapper *Registry, - ) { - err := global.Register(f) - if !assert.NoError(t, err) { - return - } - - factory, err := wrapper.Lookup(name) - if !assert.NoError(t, err) { - return - } - - // Compare func pointers instead of comparing the function value. - assert.Equal(t, reflect.ValueOf(providerFn).Pointer(), reflect.ValueOf(factory).Pointer()) - })) - - t.Run("retrieving a non existing provider", withRegistry(func( - t *testing.T, - global *feature.Registry, - wrapper *Registry, - ) { - _, err := wrapper.Lookup("unknown") - assert.Error(t, err) - })) - - t.Run("invalid provider name when doing lookup", withRegistry(func( - t *testing.T, - global *feature.Registry, - wrapper *Registry, - ) { - _, err := wrapper.Lookup("") - assert.Error(t, err) - })) -} - -func testFunctionLookup(t *testing.T) { - name := "myprovider" - myprovider := &mockProvider{} - - providerFn := func(log *logp.Logger, registry *Registry, config *conf.C) (Provider, error) { - return myprovider, nil - } - - f := newFeature( - name, - providerFn, - ) - - fnName := "myfunc" - myfunction := &mockFunction{name} - functionFn := func(provider Provider, config *conf.C) (Function, error) { - return myfunction, nil - } - - fnFeature := newFunctionFeature(name, fnName, functionFn) - - t.Run("adding and retrieving a function", withRegistry(func( - t *testing.T, - global *feature.Registry, - wrapper *Registry, - ) { - err := global.Register(f) - if !assert.NoError(t, err) { - return - } - - err = global.Register(fnFeature) - if !assert.NoError(t, err) { - return - } - - factory, err := wrapper.LookupFunction(name, fnName) - if !assert.NoError(t, err) { - return - } - - // Compare func pointers instead of comparing the function value. - assert.Equal(t, reflect.ValueOf(functionFn).Pointer(), reflect.ValueOf(factory).Pointer()) - })) - - t.Run("return an error if the provider doesn't exist", withRegistry(func( - t *testing.T, - global *feature.Registry, - wrapper *Registry, - ) { - err := global.Register(f) - if !assert.NoError(t, err) { - return - } - - err = global.Register(fnFeature) - if !assert.NoError(t, err) { - return - } - - _, err = wrapper.LookupFunction("I do not exist", fnName) - assert.Error(t, err) - })) - - t.Run("return an error if the function doesn't exist", withRegistry(func( - t *testing.T, - global *feature.Registry, - wrapper *Registry, - ) { - err := global.Register(f) - if !assert.NoError(t, err) { - return - } - - err = global.Register(fnFeature) - if !assert.NoError(t, err) { - return - } - - _, err = wrapper.LookupFunction(name, "I do not exist") - assert.Error(t, err) - })) -} - -func withRegistry(fn func(t *testing.T, global *feature.Registry, registry *Registry)) func(t *testing.T) { - return func(t *testing.T) { - global := feature.NewRegistry() - wrapped := NewRegistry(global) - fn(t, global, wrapped) - } -} - -func TestStrInSlice(t *testing.T) { - haystack := []string{"bob", "aline"} - t.Run("when in slice return position", func(t *testing.T) { - assert.Equal(t, 1, strInSlice(haystack, "aline")) - }) - - t.Run("when not in slice return -1", func(t *testing.T) { - assert.Equal(t, -1, strInSlice(haystack, "robert")) - }) -} - -func TestFindFunctionByName(t *testing.T) { - t.Run("when the function is not enabled", withRegistry(func( - t *testing.T, - global *feature.Registry, - wrapper *Registry, - ) { - configs := []*conf.C{ - conf.MustNewConfigFrom(map[string]interface{}{ - "name": "mysqs", - "type": "sqs", - "enabled": false, - }), - } - - myprovider := &mockProvider{} - - _, err := FindFunctionByName(wrapper, myprovider, configs, "mysqs") - assert.Error(t, err) - })) - - t.Run("when the function is enabled", withRegistry(func( - t *testing.T, - global *feature.Registry, - wrapper *Registry, - ) { - fnName := "sqs" - configs := []*conf.C{ - conf.MustNewConfigFrom(map[string]interface{}{ - "name": "mysqs", - "type": fnName, - "enabled": true, - }), - } - - name := "myprovider" - myprovider := &mockProvider{name: name} - - providerFn := func(log *logp.Logger, registry *Registry, config *conf.C) (Provider, error) { - return myprovider, nil - } - f := newFeature(name, providerFn) - - myfunction := &mockFunction{name} - functionFn := func(provider Provider, config *conf.C) (Function, error) { - return myfunction, nil - } - - fnFeature := newFunctionFeature(name, fnName, functionFn) - - err := global.Register(f) - if !assert.NoError(t, err) { - return - } - - err = global.Register(fnFeature) - if !assert.NoError(t, err) { - return - } - - _, err = FindFunctionByName(wrapper, myprovider, configs, "mysqs") - assert.NoError(t, err) - })) -} diff --git a/x-pack/functionbeat/function/provider/template.go b/x-pack/functionbeat/function/provider/template.go deleted file mode 100644 index d313774ccb52..000000000000 --- a/x-pack/functionbeat/function/provider/template.go +++ /dev/null @@ -1,19 +0,0 @@ -// Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one -// or more contributor license agreements. Licensed under the Elastic License; -// you may not use this file except in compliance with the Elastic License. - -package provider - -import ( - conf "github.com/elastic/elastic-agent-libs/config" - "github.com/elastic/elastic-agent-libs/logp" -) - -// TemplateBuilderFactory factory method to call to create a new template builder. -type TemplateBuilderFactory func(*logp.Logger, *conf.C, Provider) (TemplateBuilder, error) - -// TemplateBuilder generates templates for a given provider. -type TemplateBuilder interface { - // RawTemplate returns a deployable template string. - RawTemplate(string) (string, error) -} diff --git a/x-pack/functionbeat/function/telemetry/telemetry.go b/x-pack/functionbeat/function/telemetry/telemetry.go deleted file mode 100644 index 7bb4f370bf97..000000000000 --- a/x-pack/functionbeat/function/telemetry/telemetry.go +++ /dev/null @@ -1,37 +0,0 @@ -// Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one -// or more contributor license agreements. Licensed under the Elastic License; -// you may not use this file except in compliance with the Elastic License. - -package telemetry - -import ( - "github.com/elastic/elastic-agent-libs/monitoring" -) - -// T is a telemetry instance -type T interface { - AddTriggeredFunction() -} - -type telemetry struct { - registry *monitoring.Registry - countFunctions *monitoring.Int -} - -// New returns a new telemetry registry. -func New(r *monitoring.Registry) T { - return &telemetry{ - registry: r.NewRegistry("functions"), - countFunctions: monitoring.NewInt(r, "count"), - } -} - -// Ignored is used when the package is not monitored. -func Ignored() T { - return nil -} - -// AddTriggeredFunction adds a triggered function data to the registry. -func (t *telemetry) AddTriggeredFunction() { - t.countFunctions.Inc() -} diff --git a/x-pack/functionbeat/functionbeat.reference.yml b/x-pack/functionbeat/functionbeat.reference.yml deleted file mode 100644 index a3df78c4e2df..000000000000 --- a/x-pack/functionbeat/functionbeat.reference.yml +++ /dev/null @@ -1,1573 +0,0 @@ -########################## Functionbeat Configuration ########################### - -# This file is a full configuration example documenting all non-deprecated -# options in comments. For a shorter configuration example, that contains only -# the most common options, please see functionbeat.yml in the same directory. -# -# You can find the full configuration reference here: -# https://www.elastic.co/guide/en/beats/functionbeat/index.html - -# ================================== Provider ================================== -# Configure functions to run on AWS Lambda, currently, we assume that the credentials -# are present in the environment to correctly create the function when using the CLI. -# -# Configure which S3 endpoint should we use. -functionbeat.provider.aws.endpoint: "s3.amazonaws.com" -# Configure which S3 bucket we should upload the lambda artifact. -functionbeat.provider.aws.deploy_bucket: "functionbeat-deploy" - -# Configure credentials of Functionbeat while deploying to AWS. -# Available options: -# * access_key_id, secret_access_key and/or session_token -#functionbeat.provider.aws.access_key_id: '${AWS_ACCESS_KEY_ID:""}' -#functionbeat.provider.aws.secret_access_key: '${AWS_SECRET_ACCESS_KEY:""}' -#functionbeat.provider.aws.session_token: '${AWS_SESSION_TOKEN:""}' -# * role_arn -#functionbeat.provider.aws.role_arn: arn:aws:iam::123456789012:role/test-fnb -# * credential_profile_name and/or shared_credential_file -#functionbeat.provider.aws.credential_profile_name: fnb-aws -#functionbeat.provider.aws.shared_credential_file: /etc/functionbeat/aws_credentials - -functionbeat.provider.aws.functions: - # Define the list of functions available, each function is required to have a unique name. - # Create a function that accepts events coming from cloudwatchlogs. - - name: cloudwatch - enabled: false - type: cloudwatch_logs - - # Description of the method to help identify them when you run multiple functions. - description: "lambda function for cloudwatch logs" - - # Concurrency, is the reserved number of instances for that function. - # Default is 5. - # - # Note: There is a hard limit of 1000 functions of any kind per account. - #concurrency: 5 - - # The maximum memory allocated for this function, the configured size must be a factor of 64. - # There is a hard limit of 3008MiB for each function. Default is 128MiB. - #memory_size: 128MiB - - # The amount of time the function is allowed to run. - #timeout: 3s - - # Execution role of the function. - #role: arn:aws:iam::123456789012:role/MyFunction - - # Connect to private resources in an Amazon VPC. - #virtual_private_cloud: - # security_group_ids: [] - # subnet_ids: [] - - # Dead letter queue configuration, this must be set to an ARN pointing to an SQS queue. - #dead_letter_config.target_arn: - - # Tags are key-value pairs attached to the function. - #tags: - # department: ops - - # Optional fields that you can specify to add additional information to the - # output. Fields can be scalar values, arrays, dictionaries, or any nested - # combination of these. - #fields: - # env: staging - - # List of cloudwatch log group registered to that function. - triggers: - - log_group_name: /aws/lambda/functionbeat-cloudwatch - #filter_pattern: mylog_ - - # Define custom processors for this function. - #processors: - # - dissect: - # tokenizer: "%{key1} %{key2}" - - # Set to true to publish fields with null values in events. - #keep_null: false - - # Create a function that accepts events from SQS queues. - - name: sqs - enabled: false - type: sqs - - # Description of the method to help identify them when you run multiple functions. - description: "lambda function for SQS events" - - # Concurrency, is the reserved number of instances for that function. - # Default is 5. - # - # Note: There is a hard limit of 1000 functions of any kind per account. - #concurrency: 5 - - # The maximum memory allocated for this function, the configured size must be a factor of 64. - # There is a hard limit of 3008MiB for each function. Default is 128MiB. - #memory_size: 128MiB - - # The amount of time the function is allowed to run. - #timeout: 3s - - # Execution role of the function. - #role: arn:aws:iam::123456789012:role/MyFunction - - # Connect to private resources in an Amazon VPC. - #virtual_private_cloud: - # security_group_ids: [] - # subnet_ids: [] - - # Dead letter queue configuration, this must be set to an ARN pointing to an SQS queue. - #dead_letter_config.target_arn: - - # Tags are key-value pairs attached to the function. - #tags: - # department: ops - - # Optional fields that you can specify to add additional information to the - # output. Fields can be scalar values, arrays, dictionaries, or any nested - # combination of these. - #fields: - # env: staging - - # List of SQS queues. - triggers: - # Arn for the SQS queue. - - event_source_arn: arn:aws:sqs:us-east-1:xxxxx:myevents - - # Define custom processors for this function. - #processors: - # - decode_json_fields: - # fields: ["message"] - # process_array: false - # max_depth: 1 - # target: "" - # overwrite_keys: false - # - - # Set to true to publish fields with null values in events. - #keep_null: false - - # Create a function that accepts events from Kinesis streams. - - name: kinesis - enabled: false - type: kinesis - - # Description of the method to help identify them when you run multiple functions. - description: "lambda function for Kinesis events" - - # Concurrency, is the reserved number of instances for that function. - # Default is 5. - # - # Note: There is a hard limit of 1000 functions of any kind per account. - #concurrency: 5 - - # The maximum memory allocated for this function, the configured size must be a factor of 64. - # There is a hard limit of 3008MiB for each function. Default is 128MiB. - #memory_size: 128MiB - - # The amount of time the function is allowed to run. - #timeout: 3s - - # Execution role of the function. - #role: arn:aws:iam::123456789012:role/MyFunction - - # Connect to private resources in an Amazon VPC. - #virtual_private_cloud: - # security_group_ids: [] - # subnet_ids: [] - - # Dead letter queue configuration, this must be set to an ARN pointing to an SQS queue. - #dead_letter_config.target_arn: - - # Tags are key-value pairs attached to the function. - #tags: - # department: ops - - # Optional fields that you can specify to add additional information to the - # output. Fields can be scalar values, arrays, dictionaries, or any nested - # combination of these. - #fields: - # env: staging - - # Define custom processors for this function. - #processors: - # This example extracts the raw data from events. - # - decode_base64_field: - # field: - # from: message - # to: message - # - decompress_gzip_field: - # field: - # from: message - # to: message - # - decode_json_fields: - # fields: ["message"] - # process_array: false - # max_depth: 1 - # target: "" - # overwrite_keys: false - - # List of Kinesis streams. - triggers: - # Arn for the Kinesis stream. - - event_source_arn: arn:aws:kinesis:us-east-1:xxxxx:myevents - - # batch_size is the number of events read in a batch. - # Default is 10. - #batch_size: 100 - - # Starting position is where to start reading events from the Kinesis stream. - # Default is trim_horizon. - #starting_position: "trim_horizon" - - # parallelization_factor is the number of batches to process from each shard concurrently. - # Default is 1. - #parallelization_factor: 1 - - # Set to true to publish fields with null values in events. - #keep_null: false - - # Create a function that accepts Cloudwatch logs from Kinesis streams. - - name: cloudwatch-logs-kinesis - enabled: false - type: cloudwatch_logs_kinesis - - # Description of the method to help identify them when you run multiple functions. - description: "lambda function for Cloudwatch logs in Kinesis events" - - # Set base64_encoded if your data is base64 encoded. - #base64_encoded: false - - # Set compressed if your data is compressed with gzip. - #compressed: true - - # Concurrency, is the reserved number of instances for that function. - # Default is 5. - # - # Note: There is a hard limit of 1000 functions of any kind per account. - #concurrency: 5 - - # The maximum memory allocated for this function, the configured size must be a factor of 64. - # There is a hard limit of 3008MiB for each function. Default is 128MiB. - #memory_size: 128MiB - - # Dead letter queue configuration, this must be set to an ARN pointing to an SQS queue. - #dead_letter_config.target_arn: - - # Tags are key-value pairs attached to the function. - #tags: - # department: ops - - # The amount of time the function is allowed to run. - #timeout: 3s - - # Execution role of the function. - #role: arn:aws:iam::123456789012:role/MyFunction - - # Connect to private resources in an Amazon VPC. - #virtual_private_cloud: - # security_group_ids: [] - # subnet_ids: [] - # - # Define custom processors for this function. - #processors: - # - decode_json_fields: - # fields: ["message"] - # process_array: false - # max_depth: 1 - # target: "" - # overwrite_keys: false - - # List of Kinesis streams. - triggers: - # Arn for the Kinesis stream. - - event_source_arn: arn:aws:kinesis:us-east-1:xxxxx:myevents - - # batch_size is the number of events read in a batch. - # Default is 10. - #batch_size: 100 - - # Starting position is where to start reading events from the Kinesis stream. - # Default is trim_horizon. - #starting_position: "trim_horizon" - - # parallelization_factor is the number of batches to process from each shard concurrently. - # Default is 1. - #parallelization_factor: 1 - - # Set to true to publish fields with null values in events. - #keep_null: false - -# ================================== General =================================== - -# The name of the shipper that publishes the network data. It can be used to group -# all the transactions sent by a single shipper in the web interface. -# If this option is not defined, the hostname is used. -#name: - -# The tags of the shipper are included in their field with each -# transaction published. Tags make it easy to group servers by different -# logical properties. -#tags: ["service-X", "web-tier"] - -# Optional fields that you can specify to add additional information to the -# output. Fields can be scalar values, arrays, dictionaries, or any nested -# combination of these. -#fields: -# env: staging - -# If this option is set to true, the custom fields are stored as top-level -# fields in the output document instead of being grouped under a field -# sub-dictionary. Default is false. -#fields_under_root: false - -# Configure the precision of all timestamps in Functionbeat. -# Available options: millisecond, microsecond, nanosecond -#timestamp.precision: millisecond - -# Internal queue configuration for buffering events to be published. -# Queue settings may be overridden by performance presets in the -# Elasticsearch output. To configure them manually use "preset: custom". -#queue: - # Queue type by name (default 'mem') - # The memory queue will present all available events (up to the outputs - # bulk_max_size) to the output, the moment the output is ready to serve - # another batch of events. - #mem: - # Max number of events the queue can buffer. - #events: 3200 - - # Hints the minimum number of events stored in the queue, - # before providing a batch of events to the outputs. - # The default value is set to 2048. - # A value of 0 ensures events are immediately available - # to be sent to the outputs. - #flush.min_events: 1600 - - # Maximum duration after which events are available to the outputs, - # if the number of events stored in the queue is < `flush.min_events`. - #flush.timeout: 10s - - # The disk queue stores incoming events on disk until the output is - # ready for them. This allows a higher event limit than the memory-only - # queue and lets pending events persist through a restart. - #disk: - # The directory path to store the queue's data. - #path: "${path.data}/diskqueue" - - # The maximum space the queue should occupy on disk. Depending on - # input settings, events that exceed this limit are delayed or discarded. - #max_size: 10GB - - # The maximum size of a single queue data file. Data in the queue is - # stored in smaller segments that are deleted after all their events - # have been processed. - #segment_size: 1GB - - # The number of events to read from disk to memory while waiting for - # the output to request them. - #read_ahead: 512 - - # The number of events to accept from inputs while waiting for them - # to be written to disk. If event data arrives faster than it - # can be written to disk, this setting prevents it from overflowing - # main memory. - #write_ahead: 2048 - - # The duration to wait before retrying when the queue encounters a disk - # write error. - #retry_interval: 1s - - # The maximum length of time to wait before retrying on a disk write - # error. If the queue encounters repeated errors, it will double the - # length of its retry interval each time, up to this maximum. - #max_retry_interval: 30s - -# Sets the maximum number of CPUs that can be executed simultaneously. The -# default is the number of logical CPUs available in the system. -#max_procs: - -# ================================= Processors ================================= - -# Processors are used to reduce the number of fields in the exported event or to -# enhance the event with external metadata. This section defines a list of -# processors that are applied one by one and the first one receives the initial -# event: -# -# event -> filter1 -> event1 -> filter2 ->event2 ... -# -# The supported processors are drop_fields, drop_event, include_fields, -# decode_json_fields, and add_cloud_metadata. -# -# For example, you can use the following processors to keep the fields that -# contain CPU load percentages, but remove the fields that contain CPU ticks -# values: -# -#processors: -# - include_fields: -# fields: ["cpu"] -# - drop_fields: -# fields: ["cpu.user", "cpu.system"] -# -# The following example drops the events that have the HTTP response code 200: -# -#processors: -# - drop_event: -# when: -# equals: -# http.code: 200 -# -# The following example renames the field a to b: -# -#processors: -# - rename: -# fields: -# - from: "a" -# to: "b" -# -# The following example tokenizes the string into fields: -# -#processors: -# - dissect: -# tokenizer: "%{key1} - %{key2}" -# field: "message" -# target_prefix: "dissect" -# -# The following example enriches each event with metadata from the cloud -# provider about the host machine. It works on EC2, GCE, DigitalOcean, -# Tencent Cloud, and Alibaba Cloud. -# -#processors: -# - add_cloud_metadata: ~ -# -# The following example enriches each event with the machine's local time zone -# offset from UTC. -# -#processors: -# - add_locale: -# format: offset -# -# The following example enriches each event with docker metadata, it matches -# given fields to an existing container id and adds info from that container: -# -#processors: -# - add_docker_metadata: -# host: "unix:///var/run/docker.sock" -# match_fields: ["system.process.cgroup.id"] -# match_pids: ["process.pid", "process.parent.pid"] -# match_source: true -# match_source_index: 4 -# match_short_id: false -# cleanup_timeout: 60 -# labels.dedot: false -# # To connect to Docker over TLS you must specify a client and CA certificate. -# #ssl: -# # certificate_authority: "/etc/pki/root/ca.pem" -# # certificate: "/etc/pki/client/cert.pem" -# # key: "/etc/pki/client/cert.key" -# -# The following example enriches each event with docker metadata, it matches -# container id from log path available in `source` field (by default it expects -# it to be /var/lib/docker/containers/*/*.log). -# -#processors: -# - add_docker_metadata: ~ -# -# The following example enriches each event with host metadata. -# -#processors: -# - add_host_metadata: ~ -# -# The following example enriches each event with process metadata using -# process IDs included in the event. -# -#processors: -# - add_process_metadata: -# match_pids: ["system.process.ppid"] -# target: system.process.parent -# -# The following example decodes fields containing JSON strings -# and replaces the strings with valid JSON objects. -# -#processors: -# - decode_json_fields: -# fields: ["field1", "field2", ...] -# process_array: false -# max_depth: 1 -# target: "" -# overwrite_keys: false -# -#processors: -# - decompress_gzip_field: -# from: "field1" -# to: "field2" -# ignore_missing: false -# fail_on_error: true -# -# The following example copies the value of the message to message_copied -# -#processors: -# - copy_fields: -# fields: -# - from: message -# to: message_copied -# fail_on_error: true -# ignore_missing: false -# -# The following example truncates the value of the message to 1024 bytes -# -#processors: -# - truncate_fields: -# fields: -# - message -# max_bytes: 1024 -# fail_on_error: false -# ignore_missing: true -# -# The following example preserves the raw message under event.original -# -#processors: -# - copy_fields: -# fields: -# - from: message -# to: event.original -# fail_on_error: false -# ignore_missing: true -# - truncate_fields: -# fields: -# - event.original -# max_bytes: 1024 -# fail_on_error: false -# ignore_missing: true -# -# The following example URL-decodes the value of field1 to field2 -# -#processors: -# - urldecode: -# fields: -# - from: "field1" -# to: "field2" -# ignore_missing: false -# fail_on_error: true - -# =============================== Elastic Cloud ================================ - -# These settings simplify using Functionbeat with the Elastic Cloud (https://cloud.elastic.co/). - -# The cloud.id setting overwrites the `output.elasticsearch.hosts` and -# `setup.kibana.host` options. -# You can find the `cloud.id` in the Elastic Cloud web UI. -#cloud.id: - -# The cloud.auth setting overwrites the `output.elasticsearch.username` and -# `output.elasticsearch.password` settings. The format is `:`. -#cloud.auth: - -# ================================== Outputs =================================== - -# Configure what output to use when sending the data collected by the beat. - -# ---------------------------- Elasticsearch Output ---------------------------- -output.elasticsearch: - # Boolean flag to enable or disable the output module. - #enabled: true - - # Array of hosts to connect to. - # Scheme and port can be left out and will be set to the default (http and 9200) - # In case you specify and additional path, the scheme is required: http://localhost:9200/path - # IPv6 addresses should always be defined as: https://[2001:db8::1]:9200 - hosts: ["localhost:9200"] - - # Performance presets configure other output fields to recommended values - # based on a performance priority. - # Options are "balanced", "throughput", "scale", "latency" and "custom". - # Default if unspecified: "custom" - preset: balanced - - # Set gzip compression level. Set to 0 to disable compression. - # This field may conflict with performance presets. To set it - # manually use "preset: custom". - # The default is 1. - #compression_level: 1 - - # Configure escaping HTML symbols in strings. - #escape_html: false - - # Protocol - either `http` (default) or `https`. - #protocol: "https" - - # Authentication credentials - either API key or username/password. - #api_key: "id:api_key" - #username: "elastic" - #password: "changeme" - - # Dictionary of HTTP parameters to pass within the URL with index operations. - #parameters: - #param1: value1 - #param2: value2 - - # Number of workers per Elasticsearch host. - # This field may conflict with performance presets. To set it - # manually use "preset: custom". - #worker: 1 - - # If set to true and multiple hosts are configured, the output plugin load - # balances published events onto all Elasticsearch hosts. If set to false, - # the output plugin sends all events to only one host (determined at random) - # and will switch to another host if the currently selected one becomes - # unreachable. The default value is true. - #loadbalance: true - - # Optional data stream or index name. The default is "functionbeat-%{[agent.version]}". - # In case you modify this pattern you must update setup.template.name and setup.template.pattern accordingly. - #index: "functionbeat-%{[agent.version]}" - - # Optional ingest pipeline. By default, no pipeline will be used. - #pipeline: "" - - # Optional HTTP path - #path: "/elasticsearch" - - # Custom HTTP headers to add to each request - #headers: - # X-My-Header: Contents of the header - - # Proxy server URL - #proxy_url: http://proxy:3128 - - # Whether to disable proxy settings for outgoing connections. If true, this - # takes precedence over both the proxy_url field and any environment settings - # (HTTP_PROXY, HTTPS_PROXY). The default is false. - #proxy_disable: false - - # The number of times a particular Elasticsearch index operation is attempted. If - # the indexing operation doesn't succeed after this many retries, the events are - # dropped. The default is 3. - #max_retries: 3 - - # The maximum number of events to bulk in a single Elasticsearch bulk API index request. - # This field may conflict with performance presets. To set it - # manually use "preset: custom". - # The default is 1600. - #bulk_max_size: 1600 - - # The number of seconds to wait before trying to reconnect to Elasticsearch - # after a network error. After waiting backoff.init seconds, the Beat - # tries to reconnect. If the attempt fails, the backoff timer is increased - # exponentially up to backoff.max. After a successful connection, the backoff - # timer is reset. The default is 1s. - #backoff.init: 1s - - # The maximum number of seconds to wait before attempting to connect to - # Elasticsearch after a network error. The default is 60s. - #backoff.max: 60s - - # The maximum amount of time an idle connection will remain idle - # before closing itself. Zero means use the default of 60s. The - # format is a Go language duration (example 60s is 60 seconds). - # This field may conflict with performance presets. To set it - # manually use "preset: custom". - # The default is 3s. - # idle_connection_timeout: 3s - - # Configure HTTP request timeout before failing a request to Elasticsearch. - #timeout: 90 - - # Prevents functionbeat from connecting to older Elasticsearch versions when set to `false` - #allow_older_versions: true - - # Use SSL settings for HTTPS. - #ssl.enabled: true - - # Controls the verification of certificates. Valid values are: - # * full, which verifies that the provided certificate is signed by a trusted - # authority (CA) and also verifies that the server's hostname (or IP address) - # matches the names identified within the certificate. - # * strict, which verifies that the provided certificate is signed by a trusted - # authority (CA) and also verifies that the server's hostname (or IP address) - # matches the names identified within the certificate. If the Subject Alternative - # Name is empty, it returns an error. - # * certificate, which verifies that the provided certificate is signed by a - # trusted authority (CA), but does not perform any hostname verification. - # * none, which performs no verification of the server's certificate. This - # mode disables many of the security benefits of SSL/TLS and should only be used - # after very careful consideration. It is primarily intended as a temporary - # diagnostic mechanism when attempting to resolve TLS errors; its use in - # production environments is strongly discouraged. - # The default value is full. - #ssl.verification_mode: full - - # List of supported/valid TLS versions. By default all TLS versions from 1.1 - # up to 1.3 are enabled. - #ssl.supported_protocols: [TLSv1.1, TLSv1.2, TLSv1.3] - - # List of root certificates for HTTPS server verifications - #ssl.certificate_authorities: ["/etc/pki/root/ca.pem"] - - # Certificate for SSL client authentication - #ssl.certificate: "/etc/pki/client/cert.pem" - - # Client certificate key - #ssl.key: "/etc/pki/client/cert.key" - - # Optional passphrase for decrypting the certificate key. - #ssl.key_passphrase: '' - - # Configure cipher suites to be used for SSL connections - #ssl.cipher_suites: [] - - # Configure curve types for ECDHE-based cipher suites - #ssl.curve_types: [] - - # Configure what types of renegotiation are supported. Valid options are - # never, once, and freely. Default is never. - #ssl.renegotiation: never - - # Configure a pin that can be used to do extra validation of the verified certificate chain, - # this allow you to ensure that a specific certificate is used to validate the chain of trust. - # - # The pin is a base64 encoded string of the SHA-256 fingerprint. - #ssl.ca_sha256: "" - - # A root CA HEX encoded fingerprint. During the SSL handshake if the - # fingerprint matches the root CA certificate, it will be added to - # the provided list of root CAs (`certificate_authorities`), if the - # list is empty or not defined, the matching certificate will be the - # only one in the list. Then the normal SSL validation happens. - #ssl.ca_trusted_fingerprint: "" - - - # Enables restarting functionbeat if any file listed by `key`, - # `certificate`, or `certificate_authorities` is modified. - # This feature IS NOT supported on Windows. - #ssl.restart_on_cert_change.enabled: false - - # Period to scan for changes on CA certificate files - #ssl.restart_on_cert_change.period: 1m - - # Enable Kerberos support. Kerberos is automatically enabled if any Kerberos setting is set. - #kerberos.enabled: true - - # Authentication type to use with Kerberos. Available options: keytab, password. - #kerberos.auth_type: password - - # Path to the keytab file. It is used when auth_type is set to keytab. - #kerberos.keytab: /etc/elastic.keytab - - # Path to the Kerberos configuration. - #kerberos.config_path: /etc/krb5.conf - - # Name of the Kerberos user. - #kerberos.username: elastic - - # Password of the Kerberos user. It is used when auth_type is set to password. - #kerberos.password: changeme - - # Kerberos realm. - #kerberos.realm: ELASTIC - - -# ------------------------------ Logstash Output ------------------------------- -#output.logstash: - # Boolean flag to enable or disable the output module. - #enabled: true - - # The Logstash hosts - #hosts: ["localhost:5044"] - - # Number of workers per Logstash host. - #worker: 1 - - # Set gzip compression level. - #compression_level: 3 - - # Configure escaping HTML symbols in strings. - #escape_html: false - - # Optional maximum time to live for a connection to Logstash, after which the - # connection will be re-established. A value of `0s` (the default) will - # disable this feature. - # - # Not yet supported for async connections (i.e. with the "pipelining" option set) - #ttl: 30s - - # Optionally load-balance events between Logstash hosts. Default is false. - #loadbalance: false - - # Number of batches to be sent asynchronously to Logstash while processing - # new batches. - #pipelining: 2 - - # If enabled only a subset of events in a batch of events is transferred per - # transaction. The number of events to be sent increases up to `bulk_max_size` - # if no error is encountered. - #slow_start: false - - # The number of seconds to wait before trying to reconnect to Logstash - # after a network error. After waiting backoff.init seconds, the Beat - # tries to reconnect. If the attempt fails, the backoff timer is increased - # exponentially up to backoff.max. After a successful connection, the backoff - # timer is reset. The default is 1s. - #backoff.init: 1s - - # The maximum number of seconds to wait before attempting to connect to - # Logstash after a network error. The default is 60s. - #backoff.max: 60s - - # Optional index name. The default index name is set to functionbeat - # in all lowercase. - #index: 'functionbeat' - - # SOCKS5 proxy server URL - #proxy_url: socks5://user:password@socks5-server:2233 - - # Resolve names locally when using a proxy server. Defaults to false. - #proxy_use_local_resolver: false - - # Use SSL settings for HTTPS. - #ssl.enabled: true - - # Controls the verification of certificates. Valid values are: - # * full, which verifies that the provided certificate is signed by a trusted - # authority (CA) and also verifies that the server's hostname (or IP address) - # matches the names identified within the certificate. - # * strict, which verifies that the provided certificate is signed by a trusted - # authority (CA) and also verifies that the server's hostname (or IP address) - # matches the names identified within the certificate. If the Subject Alternative - # Name is empty, it returns an error. - # * certificate, which verifies that the provided certificate is signed by a - # trusted authority (CA), but does not perform any hostname verification. - # * none, which performs no verification of the server's certificate. This - # mode disables many of the security benefits of SSL/TLS and should only be used - # after very careful consideration. It is primarily intended as a temporary - # diagnostic mechanism when attempting to resolve TLS errors; its use in - # production environments is strongly discouraged. - # The default value is full. - #ssl.verification_mode: full - - # List of supported/valid TLS versions. By default all TLS versions from 1.1 - # up to 1.3 are enabled. - #ssl.supported_protocols: [TLSv1.1, TLSv1.2, TLSv1.3] - - # List of root certificates for HTTPS server verifications - #ssl.certificate_authorities: ["/etc/pki/root/ca.pem"] - - # Certificate for SSL client authentication - #ssl.certificate: "/etc/pki/client/cert.pem" - - # Client certificate key - #ssl.key: "/etc/pki/client/cert.key" - - # Optional passphrase for decrypting the certificate key. - #ssl.key_passphrase: '' - - # Configure cipher suites to be used for SSL connections - #ssl.cipher_suites: [] - - # Configure curve types for ECDHE-based cipher suites - #ssl.curve_types: [] - - # Configure what types of renegotiation are supported. Valid options are - # never, once, and freely. Default is never. - #ssl.renegotiation: never - - # Configure a pin that can be used to do extra validation of the verified certificate chain, - # this allow you to ensure that a specific certificate is used to validate the chain of trust. - # - # The pin is a base64 encoded string of the SHA-256 fingerprint. - #ssl.ca_sha256: "" - - # A root CA HEX encoded fingerprint. During the SSL handshake if the - # fingerprint matches the root CA certificate, it will be added to - # the provided list of root CAs (`certificate_authorities`), if the - # list is empty or not defined, the matching certificate will be the - # only one in the list. Then the normal SSL validation happens. - #ssl.ca_trusted_fingerprint: "" - - # Enables restarting functionbeat if any file listed by `key`, - # `certificate`, or `certificate_authorities` is modified. - # This feature IS NOT supported on Windows. - #ssl.restart_on_cert_change.enabled: false - - # Period to scan for changes on CA certificate files - #ssl.restart_on_cert_change.period: 1m - - # The number of times to retry publishing an event after a publishing failure. - # After the specified number of retries, the events are typically dropped. - # Some Beats, such as Filebeat and Winlogbeat, ignore the max_retries setting - # and retry until all events are published. Set max_retries to a value less - # than 0 to retry until all events are published. The default is 3. - #max_retries: 3 - - # The maximum number of events to bulk in a single Logstash request. The - # default is 2048. - #bulk_max_size: 2048 - - # The number of seconds to wait for responses from the Logstash server before - # timing out. The default is 30s. - #timeout: 30s - - - - -# ------------------------------- Console Output ------------------------------- -#output.console: - # Boolean flag to enable or disable the output module. - #enabled: true - - # Configure JSON encoding - #codec.json: - # Pretty-print JSON event - #pretty: false - - # Configure escaping HTML symbols in strings. - #escape_html: false - -# =================================== Paths ==================================== - -# The home path for the Functionbeat installation. This is the default base path -# for all other path settings and for miscellaneous files that come with the -# distribution (for example, the sample dashboards). -# If not set by a CLI flag or in the configuration file, the default for the -# home path is the location of the binary. -#path.home: - -# The configuration path for the Functionbeat installation. This is the default -# base path for configuration files, including the main YAML configuration file -# and the Elasticsearch template file. If not set by a CLI flag or in the -# configuration file, the default for the configuration path is the home path. -#path.config: ${path.home} - -# The data path for the Functionbeat installation. This is the default base path -# for all the files in which Functionbeat needs to store its data. If not set by a -# CLI flag or in the configuration file, the default for the data path is a data -# subdirectory inside the home path. -#path.data: ${path.home}/data - -# The logs path for a Functionbeat installation. This is the default location for -# the Beat's log files. If not set by a CLI flag or in the configuration file, -# the default for the logs path is a logs subdirectory inside the home path. -#path.logs: ${path.home}/logs - -# ================================== Keystore ================================== - -# Location of the Keystore containing the keys and their sensitive values. -#keystore.path: "${path.config}/beats.keystore" - -# ================================= Dashboards ================================= - -# 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 -# options here or by using the `-setup` CLI flag or the `setup` command. -#setup.dashboards.enabled: false - -# The directory from where to read the dashboards. The default is the `kibana` -# folder in the home path. -#setup.dashboards.directory: ${path.home}/kibana - -# The URL from where to download the dashboard archive. It is used instead of -# the directory if it has a value. -#setup.dashboards.url: - -# The file archive (zip file) from where to read the dashboards. It is used instead -# of the directory when it has a value. -#setup.dashboards.file: - -# In case the archive contains the dashboards from multiple Beats, this lets you -# select which one to load. You can load all the dashboards in the archive by -# setting this to the empty string. -#setup.dashboards.beat: functionbeat - -# The name of the Kibana index to use for setting the configuration. Default is ".kibana" -#setup.dashboards.kibana_index: .kibana - -# The Elasticsearch index name. This overwrites the index name defined in the -# dashboards and index pattern. Example: testbeat-* -#setup.dashboards.index: - -# Always use the Kibana API for loading the dashboards instead of autodetecting -# how to install the dashboards by first querying Elasticsearch. -#setup.dashboards.always_kibana: false - -# If true and Kibana is not reachable at the time when dashboards are loaded, -# it will retry to reconnect to Kibana instead of exiting with an error. -#setup.dashboards.retry.enabled: false - -# Duration interval between Kibana connection retries. -#setup.dashboards.retry.interval: 1s - -# Maximum number of retries before exiting with an error, 0 for unlimited retrying. -#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. - -# Set to false to disable template loading. -#setup.template.enabled: true - -# Template name. By default the template name is "functionbeat-%{[agent.version]}" -# The template name and pattern has to be set in case the Elasticsearch index pattern is modified. -#setup.template.name: "functionbeat-%{[agent.version]}" - -# Template pattern. By default the template pattern is "functionbeat-%{[agent.version]}" to apply to the default index settings. -# The template name and pattern has to be set in case the Elasticsearch index pattern is modified. -#setup.template.pattern: "functionbeat-%{[agent.version]}" - -# Path to fields.yml file to generate the template -#setup.template.fields: "${path.config}/fields.yml" - -# A list of fields to be added to the template and Kibana index pattern. Also -# specify setup.template.overwrite: true to overwrite the existing template. -#setup.template.append_fields: -#- name: field_name -# type: field_type - -# Enable JSON template loading. If this is enabled, the fields.yml is ignored. -#setup.template.json.enabled: false - -# Path to the JSON template file -#setup.template.json.path: "${path.config}/template.json" - -# Name under which the template is stored in Elasticsearch -#setup.template.json.name: "" - -# Set this option if the JSON template is a data stream. -#setup.template.json.data_stream: false - -# Overwrite existing template -# Do not enable this option for more than one instance of functionbeat as it might -# overload your Elasticsearch with too many update requests. -#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 - - # 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 - -# ====================== Index Lifecycle Management (ILM) ====================== - -# Configure index lifecycle management (ILM) to manage the backing indices -# of your data streams. - -# Enable ILM support. Valid values are true, or false. -#setup.ilm.enabled: true - -# Set the lifecycle policy name. The default policy name is -# 'beatname'. -#setup.ilm.policy_name: "mypolicy" - -# The path to a JSON file that contains a lifecycle policy configuration. Used -# to load your own lifecycle policy. -#setup.ilm.policy_file: - -# Disable the check for an existing lifecycle policy. The default is true. -# If you set this option to false, lifecycle policy will not be installed, -# even if setup.ilm.overwrite is set to true. -#setup.ilm.check_exists: true - -# Overwrite the lifecycle policy at startup. The default is false. -#setup.ilm.overwrite: false - -# ======================== Data Stream Lifecycle (DSL) ========================= - -# Configure Data Stream Lifecycle to manage data streams while connected to Serverless elasticsearch. -# These settings are mutually exclusive with ILM settings which are not supported in Serverless projects. - -# Enable DSL support. Valid values are true, or false. -#setup.dsl.enabled: true - -# Set the lifecycle policy name or pattern. For DSL, this name must match the data stream that the lifecycle is for. -# The default data stream pattern is functionbeat-%{[agent.version]}" -# The template string `%{[agent.version]}` will resolve to the current stack version. -# The other possible template value is `%{[beat.name]}`. -#setup.dsl.data_stream_pattern: "functionbeat-%{[agent.version]}" - -# The path to a JSON file that contains a lifecycle policy configuration. Used -# to load your own lifecycle policy. -# If no custom policy is specified, a default policy with a lifetime of 7 days will be created. -#setup.dsl.policy_file: - -# Disable the check for an existing lifecycle policy. The default is true. If -# you disable this check, set setup.dsl.overwrite: true so the lifecycle policy -# can be installed. -#setup.dsl.check_exists: true - -# Overwrite the lifecycle policy at startup. The default is false. -#setup.dsl.overwrite: false - -# =================================== Kibana =================================== - -# 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 - # Scheme and port can be left out and will be set to the default (http and 5601) - # In case you specify and additional path, the scheme is required: http://localhost:5601/path - # IPv6 addresses should always be defined as: https://[2001:db8::1]:5601 - #host: "localhost:5601" - - # Optional protocol and basic auth credentials. - #protocol: "https" - #username: "elastic" - #password: "changeme" - - # Optional HTTP path - #path: "" - - # Optional Kibana space ID. - #space.id: "" - - # Custom HTTP headers to add to each request - #headers: - # X-My-Header: Contents of the header - - # Use SSL settings for HTTPS. - #ssl.enabled: true - - # Controls the verification of certificates. Valid values are: - # * full, which verifies that the provided certificate is signed by a trusted - # authority (CA) and also verifies that the server's hostname (or IP address) - # matches the names identified within the certificate. - # * strict, which verifies that the provided certificate is signed by a trusted - # authority (CA) and also verifies that the server's hostname (or IP address) - # matches the names identified within the certificate. If the Subject Alternative - # Name is empty, it returns an error. - # * certificate, which verifies that the provided certificate is signed by a - # trusted authority (CA), but does not perform any hostname verification. - # * none, which performs no verification of the server's certificate. This - # mode disables many of the security benefits of SSL/TLS and should only be used - # after very careful consideration. It is primarily intended as a temporary - # diagnostic mechanism when attempting to resolve TLS errors; its use in - # production environments is strongly discouraged. - # The default value is full. - #ssl.verification_mode: full - - # List of supported/valid TLS versions. By default all TLS versions from 1.1 - # up to 1.3 are enabled. - #ssl.supported_protocols: [TLSv1.1, TLSv1.2, TLSv1.3] - - # List of root certificates for HTTPS server verifications - #ssl.certificate_authorities: ["/etc/pki/root/ca.pem"] - - # Certificate for SSL client authentication - #ssl.certificate: "/etc/pki/client/cert.pem" - - # Client certificate key - #ssl.key: "/etc/pki/client/cert.key" - - # Optional passphrase for decrypting the certificate key. - #ssl.key_passphrase: '' - - # Configure cipher suites to be used for SSL connections - #ssl.cipher_suites: [] - - # Configure curve types for ECDHE-based cipher suites - #ssl.curve_types: [] - - # Configure what types of renegotiation are supported. Valid options are - # never, once, and freely. Default is never. - #ssl.renegotiation: never - - # Configure a pin that can be used to do extra validation of the verified certificate chain, - # this allow you to ensure that a specific certificate is used to validate the chain of trust. - # - # The pin is a base64 encoded string of the SHA-256 fingerprint. - #ssl.ca_sha256: "" - - # A root CA HEX encoded fingerprint. During the SSL handshake if the - # fingerprint matches the root CA certificate, it will be added to - # the provided list of root CAs (`certificate_authorities`), if the - # list is empty or not defined, the matching certificate will be the - # only one in the list. Then the normal SSL validation happens. - #ssl.ca_trusted_fingerprint: "" - - -# ================================== Logging =================================== - -# There are four options for the log output: file, stderr, syslog, eventlog -# The file output is the default. - -# Sets log level. The default log level is info. -# Available log levels are: error, warning, info, debug -#logging.level: info - -# Enable debug output for selected components. To enable all selectors use ["*"] -# Other available selectors are "beat", "publisher", "service" -# Multiple selectors can be chained. -#logging.selectors: [ ] - -# Send all logging output to stderr. The default is false. -#logging.to_stderr: false - -# Send all logging output to syslog. The default is false. -#logging.to_syslog: false - -# Send all logging output to Windows Event Logs. The default is false. -#logging.to_eventlog: false - -# If enabled, Functionbeat periodically logs its internal metrics that have changed -# in the last period. For each metric that changed, the delta from the value at -# the beginning of the period is logged. Also, the total values for -# all non-zero internal metrics are logged on shutdown. The default is true. -#logging.metrics.enabled: true - -# The period after which to log the internal metrics. The default is 30s. -#logging.metrics.period: 30s - -# A list of metrics namespaces to report in the logs. Defaults to [stats]. -# `stats` contains general Beat metrics. `dataset` may be present in some -# Beats and contains module or input metrics. -#logging.metrics.namespaces: [stats] - -# Logging to rotating files. Set logging.to_files to false to disable logging to -# files. -logging.to_files: true -logging.files: - # Configure the path where the logs are written. The default is the logs directory - # under the home path (the binary location). - #path: /var/log/functionbeat - - # The name of the files where the logs are written to. - #name: functionbeat - - # Configure log file size limit. If the limit is reached, log file will be - # automatically rotated. - #rotateeverybytes: 10485760 # = 10MB - - # Number of rotated log files to keep. The oldest files will be deleted first. - #keepfiles: 7 - - # The permissions mask to apply when rotating log files. The default value is 0600. - # Must be a valid Unix-style file permissions mask expressed in octal notation. - #permissions: 0600 - - # Enable log file rotation on time intervals in addition to the size-based rotation. - # Intervals must be at least 1s. Values of 1m, 1h, 24h, 7*24h, 30*24h, and 365*24h - # are boundary-aligned with minutes, hours, days, weeks, months, and years as - # reported by the local system clock. All other intervals are calculated from the - # Unix epoch. Defaults to disabled. - #interval: 0 - - # Rotate existing logs on startup rather than appending them to the existing - # file. Defaults to true. - # rotateonstartup: true - -#=============================== Events Logging =============================== -# Some outputs will log raw events on errors like indexing errors in the -# Elasticsearch output, to prevent logging raw events (that may contain -# sensitive information) together with other log messages, a different -# log file, only for log entries containing raw events, is used. It will -# use the same level, selectors and all other configurations from the -# default logger, but it will have it's own file configuration. -# -# Having a different log file for raw events also prevents event data -# from drowning out the regular log files. -# -# IMPORTANT: No matter the default logger output configuration, raw events -# will **always** be logged to a file configured by `logging.event_data.files`. - -# logging.event_data: -# Logging to rotating files. Set logging.to_files to false to disable logging to -# files. -#logging.event_data.to_files: true -#logging.event_data: - # Configure the path where the logs are written. The default is the logs directory - # under the home path (the binary location). - #path: /var/log/functionbeat - - # The name of the files where the logs are written to. - #name: functionbeat-event-data - - # Configure log file size limit. If the limit is reached, log file will be - # automatically rotated. - #rotateeverybytes: 5242880 # = 5MB - - # Number of rotated log files to keep. The oldest files will be deleted first. - #keepfiles: 2 - - # The permissions mask to apply when rotating log files. The default value is 0600. - # Must be a valid Unix-style file permissions mask expressed in octal notation. - #permissions: 0600 - - # Enable log file rotation on time intervals in addition to the size-based rotation. - # Intervals must be at least 1s. Values of 1m, 1h, 24h, 7*24h, 30*24h, and 365*24h - # are boundary-aligned with minutes, hours, days, weeks, months, and years as - # reported by the local system clock. All other intervals are calculated from the - # Unix epoch. Defaults to disabled. - #interval: 0 - - # Rotate existing logs on startup rather than appending them to the existing - # file. Defaults to false. - # rotateonstartup: false - -# ============================= X-Pack Monitoring ============================== -# Functionbeat can export internal metrics to a central Elasticsearch monitoring -# cluster. This requires xpack monitoring to be enabled in Elasticsearch. The -# reporting is disabled by default. - -# Set to true to enable the monitoring reporter. -#monitoring.enabled: false - -# Sets the UUID of the Elasticsearch cluster under which monitoring data for this -# Functionbeat instance will appear in the Stack Monitoring UI. If output.elasticsearch -# is enabled, the UUID is derived from the Elasticsearch cluster referenced by output.elasticsearch. -#monitoring.cluster_uuid: - -# Uncomment to send the metrics to Elasticsearch. Most settings from the -# Elasticsearch output are accepted here as well. -# Note that the settings should point to your Elasticsearch *monitoring* cluster. -# Any setting that is not set is automatically inherited from the Elasticsearch -# output configuration, so if you have the Elasticsearch output configured such -# that it is pointing to your Elasticsearch monitoring cluster, you can simply -# uncomment the following line. -#monitoring.elasticsearch: - - # Array of hosts to connect to. - # Scheme and port can be left out and will be set to the default (http and 9200) - # In case you specify an additional path, the scheme is required: http://localhost:9200/path - # IPv6 addresses should always be defined as: https://[2001:db8::1]:9200 - #hosts: ["localhost:9200"] - - # Set gzip compression level. - #compression_level: 0 - - # Protocol - either `http` (default) or `https`. - #protocol: "https" - - # Authentication credentials - either API key or username/password. - #api_key: "id:api_key" - #username: "beats_system" - #password: "changeme" - - # Dictionary of HTTP parameters to pass within the URL with index operations. - #parameters: - #param1: value1 - #param2: value2 - - # Custom HTTP headers to add to each request - #headers: - # X-My-Header: Contents of the header - - # Proxy server url - #proxy_url: http://proxy:3128 - - # The number of times a particular Elasticsearch index operation is attempted. If - # the indexing operation doesn't succeed after this many retries, the events are - # dropped. The default is 3. - #max_retries: 3 - - # The maximum number of events to bulk in a single Elasticsearch bulk API index request. - # The default is 50. - #bulk_max_size: 50 - - # The number of seconds to wait before trying to reconnect to Elasticsearch - # after a network error. After waiting backoff.init seconds, the Beat - # tries to reconnect. If the attempt fails, the backoff timer is increased - # exponentially up to backoff.max. After a successful connection, the backoff - # timer is reset. The default is 1s. - #backoff.init: 1s - - # The maximum number of seconds to wait before attempting to connect to - # Elasticsearch after a network error. The default is 60s. - #backoff.max: 60s - - # Configure HTTP request timeout before failing a request to Elasticsearch. - #timeout: 90 - - # Use SSL settings for HTTPS. - #ssl.enabled: true - - # Controls the verification of certificates. Valid values are: - # * full, which verifies that the provided certificate is signed by a trusted - # authority (CA) and also verifies that the server's hostname (or IP address) - # matches the names identified within the certificate. - # * strict, which verifies that the provided certificate is signed by a trusted - # authority (CA) and also verifies that the server's hostname (or IP address) - # matches the names identified within the certificate. If the Subject Alternative - # Name is empty, it returns an error. - # * certificate, which verifies that the provided certificate is signed by a - # trusted authority (CA), but does not perform any hostname verification. - # * none, which performs no verification of the server's certificate. This - # mode disables many of the security benefits of SSL/TLS and should only be used - # after very careful consideration. It is primarily intended as a temporary - # diagnostic mechanism when attempting to resolve TLS errors; its use in - # production environments is strongly discouraged. - # The default value is full. - #ssl.verification_mode: full - - # List of supported/valid TLS versions. By default all TLS versions from 1.1 - # up to 1.3 are enabled. - #ssl.supported_protocols: [TLSv1.1, TLSv1.2, TLSv1.3] - - # List of root certificates for HTTPS server verifications - #ssl.certificate_authorities: ["/etc/pki/root/ca.pem"] - - # Certificate for SSL client authentication - #ssl.certificate: "/etc/pki/client/cert.pem" - - # Client certificate key - #ssl.key: "/etc/pki/client/cert.key" - - # Optional passphrase for decrypting the certificate key. - #ssl.key_passphrase: '' - - # Configure cipher suites to be used for SSL connections - #ssl.cipher_suites: [] - - # Configure curve types for ECDHE-based cipher suites - #ssl.curve_types: [] - - # Configure what types of renegotiation are supported. Valid options are - # never, once, and freely. Default is never. - #ssl.renegotiation: never - - # Configure a pin that can be used to do extra validation of the verified certificate chain, - # this allow you to ensure that a specific certificate is used to validate the chain of trust. - # - # The pin is a base64 encoded string of the SHA-256 fingerprint. - #ssl.ca_sha256: "" - - # A root CA HEX encoded fingerprint. During the SSL handshake if the - # fingerprint matches the root CA certificate, it will be added to - # the provided list of root CAs (`certificate_authorities`), if the - # list is empty or not defined, the matching certificate will be the - # only one in the list. Then the normal SSL validation happens. - #ssl.ca_trusted_fingerprint: "" - - # Enable Kerberos support. Kerberos is automatically enabled if any Kerberos setting is set. - #kerberos.enabled: true - - # Authentication type to use with Kerberos. Available options: keytab, password. - #kerberos.auth_type: password - - # Path to the keytab file. It is used when auth_type is set to keytab. - #kerberos.keytab: /etc/elastic.keytab - - # Path to the Kerberos configuration. - #kerberos.config_path: /etc/krb5.conf - - # Name of the Kerberos user. - #kerberos.username: elastic - - # Password of the Kerberos user. It is used when auth_type is set to password. - #kerberos.password: changeme - - # Kerberos realm. - #kerberos.realm: ELASTIC - - #metrics.period: 10s - #state.period: 1m - -# The `monitoring.cloud.id` setting overwrites the `monitoring.elasticsearch.hosts` -# setting. You can find the value for this setting in the Elastic Cloud web UI. -#monitoring.cloud.id: - -# The `monitoring.cloud.auth` setting overwrites the `monitoring.elasticsearch.username` -# and `monitoring.elasticsearch.password` settings. The format is `:`. -#monitoring.cloud.auth: - -# =============================== HTTP Endpoint ================================ - -# Each beat can expose internal metrics through an HTTP endpoint. For security -# reasons the endpoint is disabled by default. This feature is currently experimental. -# Stats can be accessed through http://localhost:5066/stats. For pretty JSON output -# append ?pretty to the URL. - -# Defines if the HTTP endpoint is enabled. -#http.enabled: false - -# The HTTP endpoint will bind to this hostname, IP address, unix socket, or named pipe. -# When using IP addresses, it is recommended to only use localhost. -#http.host: localhost - -# Port on which the HTTP endpoint will bind. Default is 5066. -#http.port: 5066 - -# Define which user should be owning the named pipe. -#http.named_pipe.user: - -# Define which permissions should be applied to the named pipe, use the Security -# Descriptor Definition Language (SDDL) to define the permission. This option cannot be used with -# `http.user`. -#http.named_pipe.security_descriptor: - -# Defines if the HTTP pprof endpoints are enabled. -# It is recommended that this is only enabled on localhost as these endpoints may leak data. -#http.pprof.enabled: false - -# Controls the fraction of goroutine blocking events that are reported in the -# blocking profile. -#http.pprof.block_profile_rate: 0 - -# Controls the fraction of memory allocations that are recorded and reported in -# the memory profile. -#http.pprof.mem_profile_rate: 524288 - -# Controls the fraction of mutex contention events that are reported in the -# mutex profile. -#http.pprof.mutex_profile_rate: 0 - -# ============================== Process Security ============================== - -# Enable or disable seccomp system call filtering on Linux. Default is enabled. -#seccomp.enabled: true - -# ============================== Instrumentation =============================== - -# Instrumentation support for the functionbeat. -#instrumentation: - # Set to true to enable instrumentation of functionbeat. - #enabled: false - - # Environment in which functionbeat is running on (eg: staging, production, etc.) - #environment: "" - - # APM Server hosts to report instrumentation results to. - #hosts: - # - http://localhost:8200 - - # API Key for the APM Server(s). - # If api_key is set then secret_token will be ignored. - #api_key: - - # Secret token for the APM Server(s). - #secret_token: - - # Enable profiling of the server, recording profile samples as events. - # - # This feature is experimental. - #profiling: - #cpu: - # Set to true to enable CPU profiling. - #enabled: false - #interval: 60s - #duration: 10s - #heap: - # Set to true to enable heap profiling. - #enabled: false - #interval: 60s - -# ================================= Migration ================================== - -# This allows to enable 6.7 migration aliases -#migration.6_to_7.enabled: false - -# =============================== Feature Flags ================================ - -# Enable and configure feature flags. -#features: -# fqdn: -# enabled: true - diff --git a/x-pack/functionbeat/functionbeat.yml b/x-pack/functionbeat/functionbeat.yml deleted file mode 100644 index 9a2627ca44f1..000000000000 --- a/x-pack/functionbeat/functionbeat.yml +++ /dev/null @@ -1,416 +0,0 @@ -###################### Functionbeat Configuration Example ####################### - -# This file is an example configuration file highlighting only the most common -# options. The functionbeat.reference.yml file from the same directory contains all the -# supported options with more comments. You can use it as a reference. -# -# You can find the full configuration reference here: -# https://www.elastic.co/guide/en/beats/functionbeat/index.html -# - -# ================================== Provider ================================== -# Configure functions to run on AWS Lambda, currently, we assume that the credentials -# are present in the environment to correctly create the function when using the CLI. -# -# Configure which S3 endpoint should we use. -functionbeat.provider.aws.endpoint: "s3.amazonaws.com" -# Configure which S3 bucket we should upload the lambda artifact. -functionbeat.provider.aws.deploy_bucket: "functionbeat-deploy" - -functionbeat.provider.aws.functions: - # Define the list of functions available, each function is required to have a unique name. - # Create a function that accepts events coming from cloudwatchlogs. - - name: cloudwatch - enabled: false - type: cloudwatch_logs - - # Description of the method to help identify them when you run multiple functions. - description: "lambda function for cloudwatch logs" - - # Concurrency, is the reserved number of instances for that function. - # Default is 5. - # - # Note: There is a hard limit of 1000 functions of any kind per account. - #concurrency: 5 - - # The maximum memory allocated for this function, the configured size must be a factor of 64. - # There is a hard limit of 3008MiB for each function. Default is 128MiB. - #memory_size: 128MiB - - # Dead letter queue configuration, this must be set to an ARN pointing to an SQS queue. - #dead_letter_config.target_arn: - - # Execution role of the function. - #role: arn:aws:iam::123456789012:role/MyFunction - - # Connect to private resources in an Amazon VPC. - #virtual_private_cloud: - # security_group_ids: [] - # subnet_ids: [] - - # Optional fields that you can specify to add additional information to the - # output. Fields can be scalar values, arrays, dictionaries, or any nested - # combination of these. - #fields: - # env: staging - - # List of cloudwatch log groups registered to that function. - triggers: - - log_group_name: /aws/lambda/functionbeat-cloudwatch_logs - filter_pattern: mylog_ - - # Define custom processors for this function. - #processors: - # - dissect: - # tokenizer: "%{key1} %{key2}" - - # Create a function that accepts events from SQS queues. - - name: sqs - enabled: false - type: sqs - - # Description of the method to help identify them when you run multiple functions. - description: "lambda function for SQS events" - - # Concurrency, is the reserved number of instances for that function. - # Default is 5. - # - # Note: There is a hard limit of 1000 functions of any kind per account. - #concurrency: 5 - - # The maximum memory allocated for this function, the configured size must be a factor of 64. - # There is a hard limit of 3008MiB for each function. Default is 128MiB. - #memory_size: 128MiB - - # Dead letter queue configuration, this must be set to an ARN pointing to an SQS queue. - #dead_letter_config.target_arn: - - # Execution role of the function. - #role: arn:aws:iam::123456789012:role/MyFunction - - # Connect to private resources in an Amazon VPC. - #virtual_private_cloud: - # security_group_ids: [] - # subnet_ids: [] - - # Optional fields that you can specify to add additional information to the - # output. Fields can be scalar values, arrays, dictionaries, or any nested - # combination of these. - #fields: - # env: staging - - # List of SQS queues. - triggers: - # Arn for the SQS queue. - - event_source_arn: arn:aws:sqs:us-east-1:xxxxx:myevents - - # Define custom processors for this function. - #processors: - # - decode_json_fields: - # fields: ["message"] - # process_array: false - # max_depth: 1 - # target: "" - # overwrite_keys: false - # - - # Create a function that accepts events from Kinesis streams. - - name: kinesis - enabled: false - type: kinesis - - # Description of the method to help identify them when you run multiple functions. - description: "lambda function for Kinesis events" - - # Concurrency, is the reserved number of instances for that function. - # Default is 5. - # - # Note: There is a hard limit of 1000 functions of any kind per account. - #concurrency: 5 - - # The maximum memory allocated for this function, the configured size must be a factor of 64. - # There is a hard limit of 3008MiB for each function. Default is 128MiB. - #memory_size: 128MiB - - # Dead letter queue configuration, this must be set to an ARN pointing to an SQS queue. - #dead_letter_config.target_arn: - - # Execution role of the function. - #role: arn:aws:iam::123456789012:role/MyFunction - - # Connect to private resources in an Amazon VPC. - #virtual_private_cloud: - # security_group_ids: [] - # subnet_ids: [] - - # Optional fields that you can specify to add additional information to the - # output. Fields can be scalar values, arrays, dictionaries, or any nested - # combination of these. - #fields: - # env: staging - - # Define custom processors for this function. - #processors: - # This example extracts the raw data from events. - # - decode_base64_field: - # field: - # from: message - # to: message - # - decompress_gzip_field: - # field: - # from: message - # to: message - # - decode_json_fields: - # fields: ["message"] - # process_array: false - # max_depth: 1 - # target: "" - # overwrite_keys: false - - # List of Kinesis streams. - triggers: - # Arn for the Kinesis stream. - - event_source_arn: arn:aws:kinesis:us-east-1:xxxxx:myevents - - # batch_size is the number of events read in a batch. - # Default is 10. - #batch_size: 100 - - # Starting position is where to start reading events from the Kinesis stream. - # Default is trim_horizon. - #starting_position: "trim_horizon" - - # parallelization_factor is the number of batches to process from each shard concurrently. - # Default is 1. - #parallelization_factor: 1 - - # Create a function that accepts Cloudwatch logs from Kinesis streams. - - name: cloudwatch-logs-kinesis - enabled: false - type: cloudwatch_logs_kinesis - - # Description of the method to help identify them when you run multiple functions. - description: "lambda function for Cloudwatch logs in Kinesis events" - - # Set base64_encoded if your data is base64 encoded. - #base64_encoded: false - - # Set compressed if your data is compressed with gzip. - #compressed: true - - # Concurrency, is the reserved number of instances for that function. - # Default is 5. - # - # Note: There is a hard limit of 1000 functions of any kind per account. - #concurrency: 5 - - # The maximum memory allocated for this function, the configured size must be a factor of 64. - # There is a hard limit of 3008MiB for each function. Default is 128MiB. - #memory_size: 128MiB - - # Dead letter queue configuration, this must be set to an ARN pointing to an SQS queue. - #dead_letter_config.target_arn: - - # Execution role of the function. - #role: arn:aws:iam::123456789012:role/MyFunction - - # Connect to private resources in an Amazon VPC. - #virtual_private_cloud: - # security_group_ids: [] - # subnet_ids: [] - - # Optional fields that you can specify to add additional information to the - # output. Fields can be scalar values, arrays, dictionaries, or any nested - # combination of these. - #fields: - # env: staging - - # Define custom processors for this function. - #processors: - # - decode_json_fields: - # fields: ["message"] - # process_array: false - # max_depth: 1 - # target: "" - # overwrite_keys: false - - # List of Kinesis streams. - triggers: - # Arn for the Kinesis stream. - - event_source_arn: arn:aws:kinesis:us-east-1:xxxxx:myevents - - # batch_size is the number of events read in a batch. - # Default is 10. - #batch_size: 100 - - # Starting position is where to start reading events from the Kinesis stream. - # Default is trim_horizon. - #starting_position: "trim_horizon" - - # parallelization_factor is the number of batches to process from each shard concurrently. - # Default is 1. - #parallelization_factor: 1 - - -# ================================== General =================================== - -# The name of the shipper that publishes the network data. It can be used to group -# all the transactions sent by a single shipper in the web interface. -#name: - -# The tags of the shipper are included in their field with each -# transaction published. -#tags: ["service-X", "web-tier"] - -# Optional fields that you can specify to add additional information to the -# output. -#fields: -# env: staging - -# ================================= Dashboards ================================= -# These settings control loading the sample dashboards to the Kibana index. Loading -# the dashboards is disabled by default and can be enabled either by setting the -# options here or by using the `setup` command. -#setup.dashboards.enabled: false - -# The URL from where to download the dashboard archive. By default, this URL -# has a value that is computed based on the Beat name and version. For released -# versions, this URL points to the dashboard archive on the artifacts.elastic.co -# website. -#setup.dashboards.url: - -# =================================== Kibana =================================== - -# 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 - # Scheme and port can be left out and will be set to the default (http and 5601) - # In case you specify and additional path, the scheme is required: http://localhost:5601/path - # IPv6 addresses should always be defined as: https://[2001:db8::1]:5601 - #host: "localhost:5601" - - # Kibana Space ID - # ID of the Kibana Space into which the dashboards should be loaded. By default, - # the Default Space will be used. - #space.id: - -# =============================== Elastic Cloud ================================ - -# These settings simplify using Functionbeat with the Elastic Cloud (https://cloud.elastic.co/). - -# The cloud.id setting overwrites the `output.elasticsearch.hosts` and -# `setup.kibana.host` options. -# You can find the `cloud.id` in the Elastic Cloud web UI. -#cloud.id: - -# The cloud.auth setting overwrites the `output.elasticsearch.username` and -# `output.elasticsearch.password` settings. The format is `:`. -#cloud.auth: - -# ================================== Outputs =================================== - -# Configure what output to use when sending the data collected by the beat. - -# ---------------------------- Elasticsearch Output ---------------------------- -output.elasticsearch: - # Array of hosts to connect to. - hosts: ["localhost:9200"] - - # Performance preset - one of "balanced", "throughput", "scale", - # "latency", or "custom". - preset: balanced - - # Protocol - either `http` (default) or `https`. - #protocol: "https" - - # Authentication credentials - either API key or username/password. - #api_key: "id:api_key" - #username: "elastic" - #password: "changeme" - -# ------------------------------ Logstash Output ------------------------------- -#output.logstash: - # The Logstash hosts - #hosts: ["localhost:5044"] - - # Optional SSL. By default is off. - # List of root certificates for HTTPS server verifications - #ssl.certificate_authorities: ["/etc/pki/root/ca.pem"] - - # Certificate for SSL client authentication - #ssl.certificate: "/etc/pki/client/cert.pem" - - # Client Certificate Key - #ssl.key: "/etc/pki/client/cert.key" - -# ================================= Processors ================================= - -# Configure processors to enhance or manipulate events generated by the beat. - -processors: - - add_host_metadata: ~ - - add_cloud_metadata: ~ - - -# ================================== Logging =================================== - -# Sets log level. The default log level is info. -# Available log levels are: error, warning, info, debug -#logging.level: debug - -# At debug level, you can selectively enable logging only for some components. -# To enable all selectors, use ["*"]. Examples of other selectors are "beat", -# "publisher", "service". -#logging.selectors: ["*"] - -# ============================= X-Pack Monitoring ============================== -# Functionbeat can export internal metrics to a central Elasticsearch monitoring -# cluster. This requires xpack monitoring to be enabled in Elasticsearch. The -# reporting is disabled by default. - -# Set to true to enable the monitoring reporter. -#monitoring.enabled: false - -# Sets the UUID of the Elasticsearch cluster under which monitoring data for this -# Functionbeat instance will appear in the Stack Monitoring UI. If output.elasticsearch -# is enabled, the UUID is derived from the Elasticsearch cluster referenced by output.elasticsearch. -#monitoring.cluster_uuid: - -# Uncomment to send the metrics to Elasticsearch. Most settings from the -# Elasticsearch outputs are accepted here as well. -# Note that the settings should point to your Elasticsearch *monitoring* cluster. -# Any setting that is not set is automatically inherited from the Elasticsearch -# output configuration, so if you have the Elasticsearch output configured such -# that it is pointing to your Elasticsearch monitoring cluster, you can simply -# uncomment the following line. -#monitoring.elasticsearch: - -# ============================== Instrumentation =============================== - -# Instrumentation support for the functionbeat. -#instrumentation: - # Set to true to enable instrumentation of functionbeat. - #enabled: false - - # Environment in which functionbeat is running on (eg: staging, production, etc.) - #environment: "" - - # APM Server hosts to report instrumentation results to. - #hosts: - # - http://localhost:8200 - - # API Key for the APM Server(s). - # If api_key is set then secret_token will be ignored. - #api_key: - - # Secret token for the APM Server(s). - #secret_token: - - -# ================================= Migration ================================== - -# This allows to enable 6.7 migration aliases -#migration.6_to_7.enabled: true - diff --git a/x-pack/functionbeat/include/feature.go b/x-pack/functionbeat/include/feature.go deleted file mode 100644 index b37796cfd77e..000000000000 --- a/x-pack/functionbeat/include/feature.go +++ /dev/null @@ -1,16 +0,0 @@ -// Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one -// or more contributor license agreements. Licensed under the Elastic License; -// you may not use this file except in compliance with the Elastic License. - -package include - -import ( - "github.com/elastic/beats/v7/libbeat/feature" - "github.com/elastic/beats/v7/x-pack/functionbeat/manager/aws" - "github.com/elastic/beats/v7/x-pack/functionbeat/provider/local/local" -) - -func init() { - feature.MustRegister(aws.Features...) - feature.MustRegister(local.Features...) -} diff --git a/x-pack/functionbeat/include/fields.go b/x-pack/functionbeat/include/fields.go deleted file mode 100644 index b58f331ad473..000000000000 --- a/x-pack/functionbeat/include/fields.go +++ /dev/null @@ -1,23 +0,0 @@ -// Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one -// or more contributor license agreements. Licensed under the Elastic License; -// you may not use this file except in compliance with the Elastic License. - -// Code generated by beats/dev-tools/cmd/asset/asset.go - DO NOT EDIT. - -package include - -import ( - "github.com/elastic/beats/v7/libbeat/asset" -) - -func init() { - if err := asset.SetFields("functionbeat", "fields.yml", asset.BeatFieldsPri, AssetFieldsYml); err != nil { - panic(err) - } -} - -// AssetFieldsYml returns asset data. -// This is the base64 encoded zlib format compressed contents of fields.yml. -func AssetFieldsYml() string { - return "eJzsvft7GzeyKPh7/gqsZr+VlEO2SL0sa+/sXkWSE33HD40lT+Yknk8Eu0ESoybQAdCSmbPnf98PVQAa/ZBMyaJjZ3xvjociu4GqQqFQVajHX8jPR29fn73+8f8gJ5IIaQjLuCFmxjWZ8JyRjCuWmnzRI9yQW6rJlAmmqGEZGS+ImTFyenxBCiX/xVLT++4vZEw1y4gU8P0NU5pLQQ6SQTLoZ+wm+e4v5DxnVDNywzU3ZGZMoQ+3tqbczMpxksr5FsupNjzdYqkmRhJdTqdMG5LOqJgy+MoOPeEsz3Ty3Xd9cs0Wh4Sl+jtCDDc5O7QPfEdIxnSqeGG4FPAVeeHeIe7tw+8I6RNB5+yQrP9vw+dMGzov1r8jhJCc3bD8kKRSMfhbsd9Krlh2SIwq8SuzKNghyajBP2vzrZ9Qw7bsmOR2xgSQit0wYYhUfMqFJWHyHbxHyKWlN9fwUBbeYx+Moqkl9UTJeTVCz07MU5rnC6JYoZhmwnAxhYnciNV0nYumZalSFuY/m0Qv4G9kRjUR0kObk0CeHrLHDc1LBkAHYApZlLmdxg3rJptwpQ283wBLsZTxmwqqghcs56KC662jOa4XmUhFaJ7jCDrBdWIf6Lywi76+PRju9wd7/e2dy8HB4WDvcGc3Odjb+WXdrc6Elrm5gqHCIvrlz+mY5bpz4XGV5dhyOHyBH6/w+2u2uJUq62CA41IbObcPbCGtCsqVDrgdU0HGjJR2uxhJaJaROTOUcDGRak7tIPZ7hyu5mMkyz2CLplIYygURTNslRXCAre3/O8pzXBtNqGJEG2kJSLWHNABw6gk3ymR6zdSIUJGR0fWBHjlytCj832u0KHKeAnRrh2RtImV/TNVaj6wxcWO/KZTMyhR+/59lCD9nWtMpu4fyc2rS2ZUU+eLKsA+mg9IvpCK5nDpaASu5YR3jOIrhT/ZJ93OPyMLwOf89sKxlsRvObu124oJQeNp+wVQgnJ1OG1WmprSkzeVUk1tuZrI0hIpqx9Rg6BFpZkw5yUNSXP1UipQaJqJNY6QFYk4omZVzKvqK0YyOc0Z0OZ9TtSAy2qzxDp6XueFFHnDXhH3g2kqLGVtUE87HXLCMcGEkkSI83Vzrn1ieS/KzVHm2xCoaOr1v88SbhE+FVOyKjuUNOyTDwfZue0Vfcm0snu49HXaJoVPCaDrz2NfZ89eY+5Alt9f+uQwX0ikTyFnuBDkKX0yVLItDst3Bd5czhm+GVXU708lxSujYMgVK3Im5tRvSympjz9OJWzoqFnaNqN3YeW63co9kzOAHqYgca6Zu7HIie0vLljNpV1YqYug102TOqC4Vm9sH3LDhseaG14SLNC8zRn5g1IoWwFWTOV0QmmtJVCns225epRM4PAHR5HuHqhtSz6w8HrNK9MNOsPBTnmvPq0gkVQph95VEAlnYIvyUG/J2xlR8UMxoUTDLsRZZ2NkBVThELAGE496JlEZIY3nBI3tIznC61CodcoJIwz63G7dXwZdYViBO8RkzapJovx+dvwIVyB3SdYTcitOi2LKo8JQlpOKNWKBnknnSgSQHnYbwCXIL18Qe5cTMlCynM/JbyUo7vl5ow+aa5Pyakf+kk2vaI29ZxpE/CiVTpjUXU78o7nFdpjMr+F/KqTZUzwjiQS6A3I5kuEGBye/ZJ7HGVO2accnzLPHyzs3elABdMuBOKdDcYacfDBOZ1RDsVDVSThw/4Np5Hne6FIp9q1QJN4CRYXdSsegYD3YgxYVAFSgMaXdGoeQNz1jP6kS6YCmf8JTg26B7cR00REfZSDLNmVE8tTwVVOJnyX4yIBt0nu3vbvZIzsfwM3796z7d3mEHk4PJzmCyNxgMx3Rnd5ftsr3d7CB7no4PttPxcPAsDSBafAzZHmwP+oPt/mCPbO8cDgeHwwH5j8FgMCDvLo//GShcW+EJzTWrLSsrZmzOFM2veFZfVOaW4wkW1s9BeGYl4oQzhdKCa7dvNvgEDig4xfRmc4m5VYbUHBRPbxvQVEltF0Ibqqz4HJeGjJBDeDaC7Wc3XnuFDuiuJfSkRogm+k/D0+8E/81qzg/HO2hsViKhHIP3bkE1HDMCUot3MKBDL6uhZ/9dBYJO8QVxGh8ArRXUhOJTePqhhjLlNww0Xyrca/i0+3nG8mJS5lZmWgngMAwDm1tJXjj5TbjQhorUacKN40fbieEMskzitC1SaVusoAokQxibayIYy9C8vZ3xdNaeKgjyVM7tZNZyi/A+m1j54Q8aQBVPIP+VnBgmSM4mhrB5YRbtpZxIWVtFu1CrWMXLRXHP8vnDzU5AaH5LF5poY/8NtLXWhJ551sRldYYevmuVuqQijQhHdKBq9SyyuJtozKpHQGPhk9rCVyvWZIDa4s9pOrPWZpvE8Tiezk5wr4DUf3dHQp3YDZj2wYWi0u1Ya9U1lbU0Usi5LDW5AA3gI+rrkSC0egWVBrJxdLGJG9Mpow6wVArBwBdxJgxTghlyrqSRqfTn/sbZ+SZRsoTTsFBswj8wTUqRMTyn7emrZG4Hs9JNKjKXihHBzK1U10QWTFEjldVvvfuAzWg+sS9QYtWbnBGazbng2tideeN1aTtWJueoeFNDnEcEkZjPpeiRNGdU5YvqBAQbKEArc54uwL6YMVAZLILJJ+tHopyPg1573xGay6C81ZbIHRU4DqF5LlPQsR2kreVzamf4OmwEt7puoI2ji9ebpITB80V1Emm0rcKS4F45q9EjYsnh3nD/eQ1hqaZU8N9BbCbt4+VT1Aewbq9iKkci0LsFyL1Og47lq5SfBuXfRJjALC3sf5TScuTLl8fRjkxz3jAkj6tv7rEkj9ybdut57qTasSM33O4M3Ah+cdyGdJqwBw4tRMWmVGVgOVjDQArdi55Hq2HM0bXLpaA5meTyliiWWmO75ue4PD53o+I5VYHZgs1+YR+PIIPtqJkI9qJ95uK/XpOCptfMbOjNBGZB10jhBEprKnRfWkWvNqk3dBVo3kxbOJwp5qlkFBWaAjAJuZBzFoyjUqORaZiakzXvk5VqrXLDKDbxssuBIhoIatxw7mfnBMCVHbNgBIMTICKA24wWLDH1y1xNEcOPbg7HRH4Ce5aVurQEcaNW1jcXFrx/lQIXAIxxNK+9x7xjsIq+QprWkFbNwvXqwz72LsngyMTxtvw8wSUNmwcVN5plRLM5FYancBKwD8bpeOwDau89VKm8HNBB0zOS3HCLLv+dVZ4ViyhTYM9pbkrqluNsQhayVGGOCc1zz3z+fLAydCrVomcf9SqKNjzPCRO6VE4fdX5wq8ZkTBvLHpaklmATnudBjNGiULJQnBqWL57AqqZZppjWq7K8YBega8XxnJvQaUlB/MzHfFrKUucL5HJ4JwjSW0suLecM7gVIzjU4P8/Oe9aIxtNYKkLtMfOBaGn5JyHkvyqKB62x0qFwfyh662Hy+2GUuC9GSLK6LioIN5GqmZXoo8aDcpTwYmRBGSUI1qhHMlYwkTljADV5KSogwM/jVrLStZJ/u+Oc6uTf9kSPvFwLw/RH1P5oxdEnVH+tBsgP9gd09IV7PbcTHSOgIG0v0MFuDTBk55XYflbK4h6OrXgHpWPOhjWPd1xzurBbED3P8LKVB5PSHi6/WRk+4SyLxwZlhArUAOxLYVRB0YIGeuJWqObImLIGQCBguHTxd6wARZa5y9MwKBOKp7O5PVW7LOvE/ZGk7h1P6ymTScrN4mpFTpNja8d0cuUrazcx516tgSOF4YIJc5XKbBUwXd7Kfs6MYfY4zVj9rjnMvq674X599N1HNmg3Misi8OuYj/1kbaClMjNyNGeKp7QDyFIYtbjiWq6K5sc4BTm7eANEb0F4fHQnWKtiTQdS5yofU0GzNqXgZPu4t2TK5FUheVAr6peAUky5KTNUwXJq4I8WBOv/TdZyuI3uP9tJ9oe7BzuDHlnLqVk7JLt7yd5g7/nwgPzPegvIpz3OGk5ezVTfq1LRT2jEefL0iHNyoWItJ2SqqChzqrhZxDrRgqRWNwNLIhK8x17lCS5E5HCuUElOmT3snT01yaVUTmfogctsxitrpVIuELycFLOF5vaDv7FMvYzSEQivpYkiQOCelqNjaQ66zZRJj21b4o6lNlL0s7S1NoXUhuar2mXr5zA8ijWqtUx5dXeJMQIO5ArRv7uYikrbd1dQ4bopXKCOGbkW8lZY244SiwpMJBX55eycRDgRYG1QpW+oWpBbnlkNDk41t6vx4go+tun3fHewO3iImFVsyqVYpQB7CzPcJ7/6fzu+C64VSTAHU6cA+1vJxqzNf9aq+b2yCZ70WJ0xDIb6HfygkxrD9cKt7dnR66PouU7g3UG1daSmcCzTrR9KJqS+OuIqUj4/whi8+AiW4YEaHmfnwUqr64cbZ+c3u5bbz85v9jeT2lxzmq5iP786Ou4GpnFpIaQJt8dz6hTwty+OybPB7jbcv2O0IcsOyak1nmRqmCEb4BDgukcO+mNeqahWx9/Eq1+nGrlgtltJfi2LgqmUavZPMmMfaMZSPqc5yfiUG7j7sWqU8VptGNOBjxNbASJIKTSfuqAdNmUqIRdlCnf+N+5BF+uFd1YIAw0jzhbFjHVI38GgPxj0907h353+9k5tpQQ1SZMzOs/Hbu5Yv1RUaPQgnZ1brJw/BQNEXx9dBuck2WDJNHF+dyuVK5cpQU+cd8nXLoHDoRP544hRFC5qxJTkkmZkTHMqUjgDJ1yxW5rn6P9UsrRHY8PKt0gXUpmHGfne5NNG8W7LP6aGHf9roQf6/R5g/dawPse3H2XrbtfhaK3JMib43etx7tYgFhTxfPY80oYpll11WdlPpydaoTTj0xnTJprU0wjn7gEiRcEyD7Iux/hTtP4vqttw1Pei4Zy9bfWVtYaVu2bF11r8Rbdh767fM2aYmoNWWyiWcm31FVCbKPoAIUYJgnnLcc5TosvJhH8II8IzGzNjisOtLXwEn0ikmm4m5FItQCxKVLQ+cKtFopI1XhDN50W+IIZeV+uKPsOcagNiFyNXUacS0hBwfd2yPAfsL1+eVHFRa6lMyuu1tmC8ywkQyL5KbgiTANMHk+EeF4qP54tU+Dz3rAL6OmEfUlaYKuwOXqvuZlvsnsB9PCUFVYZHFw2kBQEID45z2f9zv6M2U9k1YICUdk3szCkV1U0DqfNVL6JAiNttITRmubztZvPuPVHfNzFt125vbxNGtUnmCzcCMgbuDKrNWhSlgEC4UWZUV2G3gCuoH2GaSptb0+V4O9HleFjbfL0aE1fgoUHhXNo+bq0aY62He05IK+B5DpfYTHHZEfpjEVhWEzSyuAI0PoPUY5OJPaRumJ3VMYrDfoNdvjzZ7KExFSypiu6BaCg6ev46EoSAZVnPK9EmSdoCsjlvGDYKLLKrBHzwdUtGkIp3CcVqJZYTj/B9jW9KzVSyWpaJ/Xd4cy0V3gfbyTFkZc7gPkRO7joWqSAvT47OIRAWMT4JQ8W8st7Gjs0pz1eE3DuLAUzgjZikDYCVnh0G8ld0A2PRXNfVMQBOKHpDeU7HeYdxm4+ZMuSUC22YY6waReB69Q9jO5h99XyHSK4sELcdjOrjqhE/Hy8HVz5bRU6NVa472BPhXKFLNV4JnKwNxIzq2ao4wVEKpI2dBx1zSjFr1bUi06kTS4JQIcUiTjFC+yRilXeauYjWEWDBM7yvhj8sdqOgAqRSTHCtaF6bk4qsQ6uCCMsOplpJYPMdcc1IstbuvugP+3v97WF/e7C9u737fLj97OBZf3v/+fbu9vPdwW5/e2dv+Hxv/9nBfn84GAzaSDyds/Azy8GLmbU+0V0PWShc3EsqmrA7ZaCSefNy+slY/kgpCulmwMowk7+vAL9kPRGtAfT6r2vXfEwFvYKYzbUeWVMMtG4xvbID+sSsO+lWxdTJEgEPIXX+i7sj6jDVl+DuDBEWMBQYLGKiaMjhq9BAPxrGbntnAkRwkzuziybkVZXdwXUcZk4FOT3eRovLbtAJM+mMabibiUYn3GiX0FUBaTd3PW+xllDGdQhfroPgxlWlcJliis2lCcHORJZG84xFMzUhQ5gocalMHiHPOqJ61d0r1VMscdBqIMjZcpN7h48dlusKVEewKB/aA+ei1FxYgWb5pO/SXtF6hadcClLyPYpB+MpQNWUm+Z4QI2vMPfbBApg9Z5/yMK2v64j6XrR6jF1EmZxYItRYRCpL1qm0WLhQRN0jiukC9ep8kZCf5C27YSoimWZGkw4E3KANNOalNdulcVmjE7hpC/dVSkrjQA+DE+e0hlPACwNZUaHigAg1iENKTUnzsFCO0pimh7didoE8A/vZGojYFbMiMuQ4OzLGk3kyBqJV9PSpvNInXsVRHgZDW8OatRcNw0U8bHdQdAkIW8tawXYHRdsc1QHdEwQJpnApuDrFcL3ag24uYPM4iIpnIS/XHfoLkvHJhKnYXQ23xxyyTq2qbI/avmGCCkOYuOFKinn9nqaSrUc/X4TJedbzAVog/8mbtz+SswwzZCF4qGzqH23LdX9//9mzZwcHB8+fP+8k5ypDAtoE9SoAzTnV99Ay0DDQ6NNoicZXi5oZ10VOF7EpEvuRsCxHP2M3y7qTnG3Hc24WV+3b1KdTVKJ58LaU+7BOOCnxbFUMb1yAZapTiLgozJYGU+o+o9r0h/XbYZ9TtLqtd+Zzyc5OvEgGFcIf+E1AeX+4vbNrVeXnAzpOMzYZdEO8Qu4OMMfxgm2oo2tg+LKdvPZkEL3yOkeUx3YvGc12MmcZL+s+f3egfZO3TyJvlxAaDYJ/k8hPKZE9cf9Mgnl5tL8e0f0InP544b480F+++F8eF1f77LOcDG6uWOZ2SZaaHDkP7/TI0e+lYtE3HZUqFn03ySPJ8HnktScERsUtSwKUsnUidIvW+YI8mgzWWl0mS+iTo9g9JWDCxCMfF/+it7pHqMW3R6ZpUd02S4VxaDSXKaOi7XK8XTp60CGOEZwrQtsFcD7p4fFA/Hxhn8/D3x4RXxYiLmOTcW24mJZcz/xzuuGkg+pPlbLir22wTBloKp5teoRNQRM5Pd4mN5q8pPNxRnvkx+Nz8uPxKbmpNJyjoiCnYspF2EN/f2Vfsd+7kkJdO5EWBWHuNfvZgdxzmKpS9MiEqik1rEdymL69H/H7ZZfs310k/7vL4j+ZEI6DEr8+ERuC574J0K9GgDof+Tenx+dyejQI/s3p8ZROD0/cfzOnh0P7T+X0aOL0VTg9HNB/CqeHw+XfXcNukOHfVdGuyPBn0reXR/zr1MiXx++bzv6l6+whSE5m7ErzqaCm9KXXXbSczBi5qP1yd9jc5Yxp1qxmXoszhfizMRdULTB9PkyqP71gYsanTJsrmk+l4mY2XyXPzaieQf01P1nQfC1GmKiBlbXvTvuocWWgAzb8oNhAhWvikndDohBUzApD+o4clunhSQUFaV3mSMXPSJsK3Da/6Bnd3ttfdotjeeE6hVsBtGMpc0ZFFxF/wJ8gDJoWEEbJsVKno4NF3WVFt6NDLRt8JP4zch3wqd3nKyxHbRkiClxelhN4h7nkKsH7LhlkTkU5oa5XxHhhKeRbAdwwkUmVRGOyqnK5Yjm7oZgoe1RYvvn+zQUErHVl5MwTOydLPhSpPY4/LJamraGmXFmxuaMs467EZFuKwHnOlMF0QeZA6abxpMx9zf4plB9Si8LIqaLFjKeEKSWVrsIh41FvaM6zuJyKVFYIaePnIy8ZvWGkFFEVxYlPzIdXq1e8FlKNH4a9tbazSGcsve4qAX/69u2bt1fvXl++fXdxeXpy9fbNm8ul16jEjjMrKo9xgcPXS3150R60uqogFU+VtDxMjqUqZK1I9scVC0bnK97Hdoqn3MwwnlRut7pyxH4Lu4YjUbxp5Rx52B4+/dtP//jl4NXB0d+XpqXvyLQENbOKVWsUO7FbhIqM1DtV1U/2Rg8pKOwNZ1pbrm8Ptof9gf3vcrh9OBwc7gx+WVrOwx5jyzDHPefS+oWR9hCGpYv2ecfeJemsni/8d7vhMby4ev2u93xQeirnvt5kD0k549XxXsvk9eHGlaSxp7+UuXbtJ1y4OAExgnoBCqkWuzzsBAVJ9ol07T7wMTEOrKr60X/DFOaJ0ynlIqrrZ98ICqRV8WNPYacspjXif0TQLkOYSmsGDdfJuKAwx1/eU7Q5PFgvzOtK5raaeUW9gFz/EAdkgCJE7JvQog3D5KvI8e+8wIr09BnLiygVDVIvsKpIGFm7pA6xsLaH3etPEIOeFmVShuZd9zOWTmnOsqtJLmlnsbf1c6ZSq+Yen79DGqLRy7Xr8sF/r/rEubqncgJP2zMwKn0gMsINUdgQBLAeWJYdJuQipZApb7UxqewpMhgE/tH441X847K7K+P6OlGMZklHrdAHVYiF80vavVThCGOSjSktp2wTGlQQjeV/sCbEBp1OFZtGLcRcWhHNcwBNbxLNRcqqdHDsRxOV+F/alwmo3ipu2GfA1c5jmPgD0V1lomS17XlWj47mczpdqdMl9qjBZCHDCQGyIhY7Cnla1UEzdLoiyCqZ6uCi00YyfNSp8f7po46N9/RsbHr9YVbX/rA275zNpVo8ncB7BeMRGI8UKP3sx+UFWGD/JxNkK2S5amFFqGQXpsUK1QmbQu2DpxAsd4kUKEVlz2F7IOd5KI4NFbUmNG07Zqpd8WRSxePLxeoQDr1VPeZ/JMJO51gRa73F0cmcCjpF3Z3rCo2WkYLtTiM10GpMV9ooRuexInhiFamL6uuPdIKMRvGamaHXDAvScIGF9b1pIditazVXjR9KXut0xqIrnjPR9Ur94aqQYKhWET0aHLrQ/NMTXDbLxvrMz/hVlxQ5kXkuoSvqnArB1CEZ/XeEMFxq/k+/9pX9rJlpfAvlmwqasv8ZVcoshw6WLs856pAK9lKofTCj0A5ZeWNJOQ8NodpX/anoyMDgizDRCXklVaMrh2MVrOAzkaVwWaBch87UUB0Kgw6SVG6NczndoqLPhQm9RvtG9s2M9UNsAjW0j7P2cZX6uEq/2rcdjIXU5p9hjY8EOcW3NaMqndXWIJVCc0g+rfdOGtP0GvtPZjxlGq3PcGFQZxWoVjvXtfJIjfddbV9yUjJkDtxFN0xAZdL2uBqzkqFMEzKIHYp98KypmLYSw2BrjlpFlE7eZ9rVsAgdSkfvRz0y2rL/fG//+X/tP2v2n/9l//l/7D//n/2HjMgGsFXFJpse4lFvBBdlo7+MEt99XDPcMnWiQ8cXZoUe1PConJd3MMO05BnbYsL3LMdhtsIwW2mpFBNmy1G4nypGDesDlZKZmed/afxCC94vqJn1C6roXP8ak/CfT2CzuU25hCS2TGeoMFf3aEtrlcfa7qGowaaZoaSjhsyhQ61mQjPvhnOutffh6HkfmbteeCXvRatj7UhMufiQULAH7LoXSs6ZmbES/mIig3Lio3hkZlJkvhrnAmgQ03XLwZQ22C0Svs+wF/6M3jBPMaKZiUe9ZaGFEIrd92vgIePp+7VQQ8e/C08kZISlMty3I+cVikeFGcN1EA5MNRl1yNVR8l78wBYSHE4NRo6H7DgyUmu/KU4tkiwjcLxiYYJRgA3nnlEdbYN42JgxD98LQr4nr3yJAs8Ho/4If3ktQXdBD4ewKmkkzdea53O8xg/RXGH/PxVnH2HVE1/CPYyfgPEEH4PDx3UpoiABYV9yMY2J5U6i5L14RQVUSVea0Nza8gsf7shc4XYvjLGzJ114nyJyU23LdOkBQt76e243xphpQwpLbJ4yLEnuyJkQC048JEIGdeK8By6ucA4XLCP39ihx7SyRVZz7HLokQ9eleFx70kAznvDu3cxbP0PqvBqP6dh2FJYmZlrQZir5fQ+3xkN+IuNW3ceXZdslY8GW4dj1I0HkDVOWhCB7FwWrCSLHL3H7ADyd8gWyLsviMJq1XE71GjDfGmr+ei0hPzPCPhQsxe5d9uCnWUbWjLL7Ya3mhVvTC2FmzK7rWtXXjCoyKU2pOuKP7ITL+W2jflw1hb3x9T0Ke/RopXCiU7upIDJvS9U78AXosX3ZFpZKTuquWbgiqjqpYWGdWnO3nquxbDUU76uASGPXogs50i5o1FOddja48wvbgVvUMu5jzeLwHHbN4ip3813t0KIJQE3NoBIrapea5VzUGsFizy836tg3UgMfv6hjrO+a0JOhTky/XeJ+f2dRfSrk1TC2vx50d/T1+vUAb9ySHkpfwQEpup/zVAhYYhOIQOmvqitcrdndUq3hwrbHAZ6qNVwYFlrE4U781hruW2u4f6/WcPF29DXzQTJ+ef3hYlC/NYl7erp/axL3rUnctyZx35rEfWsS961J3Lcmcd+axH2VTeJiJfHL6BQXQfStXdwX0C6OF+Awj/jkIz3SWK05WqH4jRW8J69+2exqj1ZVTv6iOsRBS7Io8NNhCuGgFW2MtItlKXHCIDXv6TFcRc+3Bxixn6/xW23fky+o+1vN3fmtBdy3FnDfWsB9awH3rQXctxZw31rAfWsB91XftHxrAfetBdy3FnDfWsB9awH3rQXcA1rAZTmeuz7O6+VL+PP+hIxlCtmAyz3nY0UVZ5pkC0Hn6ETxBJU0Q0+a9HUD4GbD/QzhnLJgyvWkAhmpMY7cSoc1PaPQz702zxoqhVVtFzBovCEw9mkJzgJgBsfTLsY02FI+JePQQ/M9OUEE+jkX126+BdkYJVmejzZJKudzSKkAB5EU5GcuMnmrq/cvENw3WBBiY5Ro2fXeO8E/9EGZbeHegqUGxiLn464B5zR9c/EEGcm1KkjJt3JCn6+cUIP0X1F1oQbk34oNra7YUJPU32oPffG1h5pL9ucpRdTA7FtloqerTNQk7Z+tUFETv291i1ZUt6hB6G9ljO6gk9U+k3m2tyLp9epkD6d4EDx6RocrAujip6Ph4yCqVNoVwLS9t/84qPbctfdKoNobbj8GKp0xtozEfhRUFyenp+cPg2pFKkfNv+ts1eYBjEdKni/InBa6q3ICGGdQf1hftzfzNVOC5TvbiXdkLIFuQc2qHJkvyjxHiO0kLdwbwB8fvnd+gvcXYOPvbL9/FEIsgdxEw9JQiXgFdWbO35F4Gt+Q2/u0LdotFD/s7z4AC3twUrFYEQKYhANxpzBNi816Pr83I9TAUzxnfajp9qT6ccGSCLBVY9sIf34Esuc0jhH/OHJ2+KsbpvRnwM5N80jM9pOd5Pn+YJAMn+0O9x6AIp8Xq7wPOcJbkFBIrJDKuBY856e408iRIA4K0u9DoAg8RiK4iP3FXaF7O2fCxZSpQnHhqo1DztoNE4RODFNEMaSYy9/07XmsvtgHPCs9TVGhg/mvscSCTKEyR9ZzKX63GGUBmbxYW8UoWlX/sNBjanRdx1MCH6amViFkwhVjCxAUWC/GzBSjpq+YKxCyPRjubg2GW0ZhBZb+nObWaOsjcfrOmQgVQjoCMdP9g8FOusueb28P7YcspXvP93cozXb2s2zyAAbxGVFXsBlWeHUXdsKnSLOL86Oz15fJ6T9OH4Cis4NXjZeb5lPwWwvi+v2Ho1PvnIfPb4KbHY/gtfsJEO5NBBp0/t7k9QX8ec+9yQu8MXEJH3bCk9cX5LeSwQaE+kJC3zJVbQT7O9z/hPRnxmEvhiBncNuKac7CWAtSKC7hhmTKDODlhnWDbowyoaGo1CE8P9okeH4v/CTx6BBO4BPx8R7U3fiYkJyM04bcfo2xL7QWV+ZgQJv2lqETBdcuZHHAOG0o8dXR5lNketcosXSFw1YxCAp3d1EBASrcGxjyQ9OZm4torOdGFDOlEtE1tb9NaHa6uJwxAjEL12zh6FUlWfuFQfpr5mat55CPF+T0+KJyR79lqVSZGwtkNEjW2HM7r9DBH/3kgtzat06PL9zwzdwju8aW97AMBgQeQ0g9w6KhtYIP9jnP4+TIkDkXfF7Oe+7LMK5HCkpgRfyGNXRGFjgoQdBCg+sq4qVnDYowJIQSpnCgcvDMWYyoJoXUmo8xiiSDghtWL4zKm/hyczJi4xagVJO01Eb6cnDNLHaHc5rTlZUZwF4vFFMvwoL4Sn1V7TXf3waOedX23p297gTdjrYqXcdX+ItFI8ae+kD2+uZgFPac9Bl0+GrBRKZ9RA1UaAFp5UkSD+hxbx3/w0Hi/+ukwiozFpuJ30bGzYkaoJOCKYjdjWhzBm4wcEPKCTl+ffTqlECNIlcvTuY3ViuLhNP6usYaP6NIxJio6IQUDKUGhOLoQloSh+uYaBDYlwk5C7JKSOOjJptj+kzx0W8l06HCwcgeOyyq6BEtC4QQ3xE17pfGmGXiB+8tmMwh2NswdQP3WlZ0A8JAgc5V8O5ems5iyc4mIJhq1TG4TqnKWJaQX5iSvhrQHNylMxf3gTK0IuC4ohpO0VGXoJtRV9gI73JWNcF7pIwB3qzBPWM0Y+pqktPp6i4tfcDNNnFZ9VZM4swEZq71mypYamplmw7J0VGPXB73yNuTHnl71CNHJz1yfNIjJ286nMy/rr09WeuRtbdHPhbnrsrXT7o0FidMM4qvw6h2oQ1O6yiUnCo6R9YLtzqVYQepBkxhDZp4IKhbWfCqfAqKBd1hWW8Ph/U2xbLoSHp9cuRd2IwUeIGFChR2BXBXQNdcQK4P6q01VZaQOdOaTlkSB5BwDaFCjnZOgBl/LYjDoGoMlIGIpnjMO2n0t3enb/+rRqMgEz+brqCcdojnBJojH1ULaqJ7lSciHIUN0OITLziLXalMn9IipOiDi8OqgnF92w3MbdnZhronFgIy3N7fjFNFpK69UQnxOLeUasJ0Sgu7p6hmZDjwOaGabLw/OTnZrBTwH2h6TXRO9cwZer+VEqrRhJHdUAm5pGPdIylVitMpc1aDKz+b86ha0oSxLB4Bqskql8f43vTIe4VvvRfAf8zdIz7sdA3r/Ifn7X3L1fuScvUCX3zmpD1ecyo4DO/LtGsJi68ot+z29rab6N8SyVAEfkske1giWcVAn8c8cFbS/ZrF0dFRvaSSN1WvPqXmwVHLQ5fn5OzcKnIMGv+OYs/GqOFi8D+OvKfP8Q6fTHha5uBAKjXrkTFLaamDV/qGKs7MwptGMafOqdHWJIyKeSfk9IOB4sEBvqgqpAfUzJhiWOBX6CQizqjSWaEMODfBmwXhbFDq18zYHKqZREOjXoAvwe+Mag5B9WHEG65LaAzl1BWr4U6k6jRzIqeJtXeqP4dNw8frwZ/DDPBzdVfBef0GAjdr0K1wU6zHuyJ49X2QVNZzFIZKfJbx6sfWQpYqKuIe3QpA8NiU3zBtH4rvE3rwRRxjhlXww7iZ0GGUCcLWvBhYFooKAO/ld3cANSAa80vhi6IWTDn8N2SBXtd8YYfQUoYTxdlquC02E3IkMkKdhyaM2arrazfV3bcT3o9vrTgnDFr8HRy+obdvWrv3OT3+2L3PK2ZoP3ZS+xZ1zgv96a2dOy/aowAexX4ruWLxMJ/EzKfHF+HWHQ62QHfsg2FkQkYs1Yl7aIR5nB6MSiqCqgSyqNQGuybDFXfuykjGDpmfZ0zgWsLCpkrqSIPzld37fec0dRcaFiAIA875dGbyRZWlUXl6Kmzg/Sg/KGcGW6VPlbvhptm/LKi+zko6Y3PaoD+pZW51sNQwGSSDmKPySY2jXr4gP4FT6iOM1ZmH9ZKL8gM5/cDSEk3fl1xcw4cXWGdp4/Tli03ooAhl8z+Z+T5D3NErms6g2HUce+SIbKnVHXd0sN9fPvRovDDsSqpsqULDj8Hhh4VhRLPfSmiBIid3A/6SG5MzcioyTpcPuC/KqxWeX8fn78LxdS/Vz4RhS0etwYnApbiKAtMfE7/utChobMlEpQSFEkkW1HVdMT05s+KCGpcAFjYuN3F7PuVDCjK42LCKm68uOKHX6Et1wSWIilR66YhL9gEiepbAepJTY1h1c1yv0ckxGh2HYxlhOZuHtEcMPV8UbHm40B2e0DFfcfzW3+thW5ajjqJsqx8w/PvMt1IjG0c/nG0+FI1VOlFRRtcvGJv7Ylk4V3i7Cp3W8CiIgHTzPhBMJoxaxPVin6xEmyNmNcGnUtQ1pVwtD6+vDT4MsSVRuNX0AFcH/9Ig6ys65isC9eN7y1McNYg3Fw+l+AqPH8cd951Ay0L52YXaA3eai/R8qnMBh3uCc8GFMS0DmGBRxtajQqd8zFRrrcNJbe3pT4mP0uW4j9psGBK8yIJRMyMjlk8Sj3Hy/Wj5rRxeSmd8mbSTDiFZ63dR18JmvK9/K10G4piOec7NAlLbFR+XMcn0A7uIBritBJbFMgH4DwL9YkaFkIK44UlK87R0EcZBTXs00KsMG7DMd+H4EXaVixR4KIwrvChtgRjXKl4eQl9v/EpOJsv1MXwSYHG2TwBX89+XoexDmoW0gAy12O1kD4d1hWdjC1Q71MMhvOHKlDS/Wr4X0oP0uxaUbr56RbbHAPz41X8EtA9c/ak9cj/XkQmT/dFHJmL8wCPTvfQAFeOxG8VRzRMrMNODYV3xhm7A+bAtDXWGrkJFpBWB6TVMV4WpKvQEaUYQKsV1hMzS8BuWT1aYWeWHJ3oxH0uXgGS30ZIWRXDgKOW6Cnq/bfhi6dpZVES5Fq7YCVxGLCBGLWzed9gNd47bHZ9zwfxFwaCXWs7IhBlsT+mvdaBAXko1urlUHIaLHntuNMsnUR1ggaM/QabFirpbAJExsK8RLI6A122pbAUQ3F3SsQMCF0z4ETC6K9514O1jE+v73dD0+gq6hC6xZW55nqU04PyZa/NdYvWKFJpr+pbUXCPpLLcWOaR6sA+mjuRnClgIy9iLg0uw1gf4+eIUNKz6HRkswQv+L3pDk5yKafK6zPNzCUHlp/7xWIjc+JsoL0TCF/cLEbeBay1IXSoVVMz4YO4ozFQ1yQd+MoqnNWFQdc23jxJoUOQ6U+pWI9FG61ToS1k1J0fhVEV8vJRBNMF9n288HioeUhMyHiBiRkyrMUjoVy4nERJuPD8U9WV+LJdBMURisYeq7L2otasLkMbAlNBOwY3p05gghiduGICt8sIgqRTCKYljZm4ZVJKL+pfSeqdTnIwLbrDXkV2qXGqL25FfiY+TG1rW+CEh/0mU2IQmJ3NGdanAz6NDZ+s2ZaPH4LrD0GsWeDgmc8weFY3nbC4hy5BpO4wfLqso7frK3vAgkQybQ1R2qVhCLhiuuWvZbk+6EaLNMYnL3Sp7LxAUfA0JWWELx4llDlIoSmSoady9ftL1ZtrO0H+6Ro84eogD8RHmruZnpLrHjcIwIzzOehPRW+TMWDYC1qgiDWZUeHqn1LCphPAOP35YdCtIRkCoPs2yUY+M3H7qw35i8JVVkvoYzZGN4r6QUYkjYYHL80VsQLhEdnREso5YolIz1S+o1paYfUw5rS/GlAlzxbOrFVe3m+IOspvL4+HCifBeUSpfrslrHyMALeFZFZSFIQRAmdAv2XWQxabXkarGoUW2v6S5qZecqjclwn49Elq8zawOknomqJdINlUzZddcOYQ1YDRbZcW5ugCKTXLoPj5jRJYmlf6ooyaAJO/q/+DqPAEZ1td1LBy5jmH17XPmly8vvJAKIzqAU6aiZtV23LOTkEg8ZVharRJo8LiVZFzrEjtkV3e69dXxnCo85V1kn6sV5StRNat72QWsjejTt6w+hPR1u6vBooehyBUGwUBDVBc9gj3Kw7BQZeGWWwO8akuGpRcaLeQr2x0qUNeitISM1goKeTJlGcORxV2HRyHKY0bknBvDGt2dO/rWH1YPjCq0+i5iMpA4YnwkEHRIidOpiBy7jLFab1jLJVFkSjXZnGsY6COTZZJpiJsNy9KYt6J1PP+982oupm5aVwNPyPb8sQS2y+uWIHa/jOwsV36Wq7uGrsECJhyytns+3uYV3YJ2h5vj7KQtW/16LWuF+1NiNScfFl50fD6RpYIorGOc03eLxnoJGKzKQ8BGLC4w/M8Fh7s1sAN54MmMM0VVOourTjWPwcoER1GzNuZTMi6h1dYaROpUI3Km6wHqkbTPDVNO4WxMcegO0RFZOH09BLgRKHDvAsbdY9W6pobfcLNwuWihoiyojXAmhcZlbka7KCNfeMWXtqRxa1Fdjj1YTQUjjO8DI928EI4O0sBCWDAVqPF7aPGvQ497HclJaixnwdKESL2Iku1gy9qR9hF/wtOd92fOlk+jtMFQlAKltD3fIGIVai9HlIua+/viB6VmQW/PmK6VFnUWvCaliDr994hiU6qyPF59UMDhaWJNydJ+kIpY9MAHDJGIqOvLG6ZA0YeaQP5I9sY117Wjy9U+QVOzU1bs7u8e1ImPyt5HZMFd4VnrbjfgIPVz3b6zVS87iqSzMm/CVVQUUjGKdZcFijmwxsYLjEsueMFyLtidPI31v1PXN+9/h7KpKDaoib+q2uk6WGv0A2hZCDm7owN6fCoLMrdWkeamxDDSnvO0m1tJwrRuo41ZR7Aqatn+zzROC6+VdvLXqmhgZSyH/HS0TeP4bZfx6+4SGopIzXKEZYFX8WyBNQnl+jPCjZMSDUjmUnAjq0oZ1RBWO5TVitk//U22keSasYKUBeqI8FK8uepUTal23oM6Ha3ijjsupXkvXtmG5tTOZtgeDPf7g73+9s7l4OBwsHe4s5sc7D37pZ7HYM/m1g3p01dMdNM0SjyIGkUwSwkSS7G2lrX0oGyDc2nlcmrJ7Y4bbO1J09o5k8tpz7ngcjnd7MWTxwWS0ZxcuOMFa0NUoi6ulG83RQw2LDrUFZuDzIa6+VZT8zHhMLw1MWtzg7ctlJuYy6zMK9bHHkfYqcFXZM+k6VV6bjxMx2FT0HTGkogWYXlLtUzz9I4rxcabXBSluQrREVRIV1LCu+BKEz9A9Sue57zzGcxVAx4ZdjLOiZu6Fn1OIKsuTFvnJJRTSHW75/FvJjLYQJjPZ6r8uVqFkC5Z5AUNzC4y742xa8pb3ZeYWKYIwl1HSgVq6zRpHiTIb/bg9N97tSoAbs8aSL+TY/DYZXXf8wovo36iekY2CqZmtNB282kD11FVhT4Iy1P01p1kBsKPKaZ4Re73uRTaKIs+eG0hZcFqjk2mH27v7O7tPzt4Puj6dPTD8UkN9VXeoJydWGy8Vyv2ezVgPqC7k73BIKtDJqasXRh8eZ3kMpwJ2ALES1WqFL9hwaJLmTCK5q4yi5GqpWGAbuE7f4AyMKoOnFgXb/ClVxfyRaiYmDhJWZ3EuZat0WvaVDzBnLmi8772Ntr69ry2AEXnuzvLNb3tdDeeCef3srsL/a7WDNO6nFuNQUhicQNrpxc0BXf2+mSvmZJC5nJa6/hjjxp57TNsuT6s0Yr8ryZy1Td+uUdLndl7yXAwXL7k/DVvCqMvzM719RAeZeiifx1z9OxAfT9K83oICr15tSH+OQaldiGhMZndvuyuUqLUNmwhANXbdb2ZVbcF7fxM3mpBeRe37aE5U8YrMrAXahcUDfeVczRN2o7PquEDpofNsNWtxsIwAEGt6GJ0wJEZFRkkhFzO2AKSzG6tqQxNf/w2VcziDPdF1ZeoZgBBlMwrrLmBUWCnz1heYEyNNpYZbmcM3H+hNFQq5+gDItRAQt20zKkKNasq01FZ5apD5bEUrLF+TadamSKLs0TV2qCKEODS1BRdnqkzH8BAQVlVFlgC17EVNFy2JjIMjRZFXk5BE2h7UqpEVwo7QXjtGfXhI1AF4fzd7Pl9gyOPGqUcaqZgdRsMNy72+bv0zBrVvex/EN3r5H1rZTf7YIKPwHKtMFyFTfbOcfmdykHMLiE+BAt+2uf8wBuunJkuco71RLmxFlrs1CmoMnrTcnK8Wbxy3yNA5YlURDFIS7/TTLc2ATzhWoxkMr2qHNBWHFjdJyRkYZE0gqV/WVZtK2tfuGR7AMQozm68tT66wtUfwb1MqRn0GMKek/KGKcUzx6w0Si72+fQe3B4pcmYtUM0YGb1AcQXJNouC6ZEX06NTq1ryFGEkb5lTmztOsgtWkOFzMjg43N4/HA7wLvX49MXh4P/6y3B79/++YGlpFw7/Ilj5eE4FnTKF3w0T9+hw4D5USq4VdboEMYTdzrWRRcEy/wL+r1bpX4eDxP7/Icm0+et2Mky2k21dmL8Ot3e2v4uI0Qj0CEvVdca6C6Uv+pi1huRjT1mH38hX+MiYkC6/MMhwPDsjdzP1CwKBBZX1THlu9bfgWiqY8gWcwkkqDHhM7JmN9ZHxhqelzL2WxhVBc73uXL1gqN1Nww2d18Oz2r5GuYk1IxsqgD21fAuW6JyrTvEGYXr2CHS+S9QOeOUdihCMQD+yh6II8HuVnGK9DTgOC1l6y5VsBNzcPQwWrkRNJQxaFf1B5dThCF6PqjFkFR0buswEPwRqFnb0SNjpUM0BjygrR2iexwu81LLexKnpbmHjchAvSgX8VJFFuCK87owDJyIU+bV6vtYydeEmuA53KF+mJoWrnhx28IoEk0bMkOUMPyvEAIdLiEOrW4168RFDxSIob3DicKhDGq6ao9u762p1NBO641B1ZK2JGFdQelUZ3OsXofZF1z5DdzrsKlRUfH2ei4V2Pri29/2lnEbe5jmqjTUVoyq44U3UkIzsjOY4JC10KLunrqPbLHAkXyz03OqpM2OKbBM86tjprBy7UAV/D93oRRpG3MB2Jb2qH0bfodj3x1X/qLRGpJhu3tW9pbaMilG9uozNtzA6uZ0t4tIVPsysLaTajueOYBw7GtDN6kE8BaXciVZLUcfgIcqnFq8Txv0ZVDAfRgBvj+oyxQ0Z5Ie7mnKvIN1GFWjV0T9bVL3ELPIh6KvRR53csjGBrpOuIpZowBMNaXdvxgR3x47V9awQDMZMOBsa4AUxWltnBBKZcjTOJQRjaG7YqINpLqGAl2tDR0oRLvnrav9H7X7F6i7MFTCbm4C8e/uS5Fxc+9Jg9/fP9HzZ5Do/CrYrhlA3nsahcyGeFgXFUWQx94LSUytBHzkJDsE8tAe1Yni6zqWA20w4csONKNCzvSq+SwcKiLhW3hbMsfWXwQB8jUsvD9fXVzrSEe/SGie5pJ1R02+5viYwAtiHikvFsTpXUxBqJ6uIljkkUuqofOc7zdztGaAG91furg91AbtzkztgvxJSLdMd+U4k1l+DL47/zjIY9iMI9TAOU6cUroADEgPLM8PBoMN/OafcNYx2jfIXsoR1r98ouRMBJQnUE9YRQLp+gWiHuHX+SGsgUedSBDSQaq6GD2hJ2OC6cUfgy6UsQb0HpXetX/g6LJiweteRDtHqjUehkhHC72/eMDuqFQfQg2tQel2vfs4+0NQQqDTjatg7nSgKCIjDATxs1R1muAlqUeuGRWb9A26t7qEUlODFAOMwQX3/1A7M+y5sfw5VzoOxEEaMq6FHtfbwKX+v5OMrYqPcSyeduEvGsvAHdxRqGlYCApbdrNz5FFIpNNcm1rsdZ8auRhMaf3e1JHA6XsBnzCyZoV/TKJfTRMPvif89SWXGRokXvv7r6niNvflVhhDmSLspWopK7VYYpdqEK3ZL88jdeHZysRmiUWtvBPXbsTXhRhN5K8KMWMzNnu9VlbYwbioLDPC9G90oTCkg3D5FntV52lC1TCLy/feEeAn50ZtCF+Ic3xVGHIF3hlVcyh2XhXaf/i7FCgsJ3m+k1lCyG6ISHHaFA0LoaHMJGA7mui6SK0Yzr5O5w9ozenXhEx2TuAE9c1TxrLFFn6aswGI0YVJfGxMq7FO7/aUA0+/sxE2+dloqWbCto7k2TGV0vhaV66bjsWI3aOP6xy8u1zbR5CQ//XQ4n1fChNPcP9Uf7B0OBmubDTHazjT6wrxUZsbVI2MeITyw7oBqhPKt6XLcx+DHNTjpe8hSGEgYnR2kUuRbAZVRTK7uESbseusoQtLJ1QwCDGTk+EKkoG5uoeySgtLpnDq+JGkzCv0zxi46vxIUTqlzTamW6T7yKMZpmg4CxobGaF4jkyDcuIDI9humDZ967OoeniWsCoEh525ovBfgop+xwsxao+OR5C79KmcP3meLOMHP1TsVYHiSIqcpu9M+ucMuqbb8J9kn80WHhQJTbO1tPxtmLBv3J3vjQX93e3jQP3g2GfR3abp78GxAdw4m7H7rxfPDhNJamdAXlH6sTqjVI0rNlE/qC5ER3Yl8k1KgNU+1yzSL0q3AXVrvRN/wOHxabm+eLXsy39Mu3HcL9ykZsPpw4wczuNgh8Kt4ZB9QXo+lZTuG60mTRsMcUXYKMr6pVic81AproZPn2R6lu326f7DX3033Jn26vT3u7+7uTg4G45003T5YFl2j+HS6lOfz7koTJ7WMuhqLueGXT+F3zzun0NVKG95UxHfTBl9Uz99h9rxpzEx6d0jUQ7FbYU7y2mWETmiv3Oap96KrT9F78T7IyveEfA+i772wn4pyrMsxfobwSFD+8W+rkSn8CGfAWpcEXVL8cRdU4MWf//uerOYjbJvdSIGFxjuteBTILtZkbM3CenC6y9K1v0Ksvs9LhZJ8KPf98fcC+oq7YifO6owuTEC/gStYf0D5xF//NxXZllQVsqQWZdtznWTC7dx4gVOe+Qt48qqKcvj1xdmrf/pOp7pK8XWCXW8m+LI7HNxdRyMNFpzE0CWAZUjNBj7hfKii0NyFzpOkymJM+CfYa+svqYtWc8FrOSZG+aE77zX9BVi1xBrDyKEFMBwgeAfXEYZKDZZOW1mZlKrrGK5HmC+2isKXrjwfaK03VC0szxQ5NZb3E/ITUxguD92N2IcZLTVcHuauFgvKgLoSa5Wl4CDncR6oq918w3pwkwq9AbIeybhiqZFqYVX3VC0KEwdWoOxhPTLjWcZED9Iy8F8p8kXPKY49cqu46bi4W/91zT+71iNr+LTvE7BMXprM2JXmU4HJ5Bmf2gOG5lalN7NlHK2P70qEnaNJmKwKjOdTNMTcBcTdDUjieLaAhfZX814Aul5twe4AczsM6RvHgjfKPqkg3MX1MKn8ZkibCtyOW9QZ3d7bfyTpMRXqI6byEupfFLDK4e7RzwDZq2iptg7tdSuJHss09hMX09WpJeuNpnnL8kmUaxEyxkCmR8Vb51SUE5qGegG0uvS9YSKTKql5JoNhHNsCR4Xlqu/fXEBniK7OMfPEzsmSD0WawIXgY0m92kT9+6/RaincBEHpJvmkxBY7uZxO7RYHsSenihYznvqKS8HhEY8Kmb6NYDqjSm38fOQlozeMlKJy0nHfLAZfrV7xRkQ1fuVtoZqUwqWpt1cMuplcvXt9+fbdxeXpydXbN28uH7tkJZZObhesfBJH2AUOXwtbgIxLFGVNxEJYATmWqpC19JqHYmYYna9409spnnLnw3hSua3tgjP8fnfaYlJt9DDoAzf86d9++scvB68Ojv7+WNJ6h/AnKH8ndj9B8mEtHzQwBx4KdiOEwBbMMYLTsn1EbA+2h/2B/e9yuH04HBzuDJbPCWjiZ/fnUqrtPSfe+oWRPpYjlhEd+x77OEdc8vd6TZC75IXr/+z7Ess5HhwQ2QJpnVEycO0WAVoE1a4SrJohZa6r0JEbli+wUgYqICjg2irep5zNIBQ/kczdmgVePU65gTqekY7hSyP44h+R/szIGGulu0SGaEE6xTqtrcVHZPYD6dSVg/0w4woMSN90A62hZe0pSH1CZqu9X7em0ijP6KnMv8picsYqVsbA6kDdBiH+Fnr2wzBuAdG0Kgu4/xvN7VQjd1XA7V5hmowAiyjUyWVlY8K9ZRNT6d/20R7RXKRhOH8L4eH2uxRqSzbyiOMaWU/e+AEGD77gejBhAKhlEmS0DqK3BlcFpR8/TkFwZlAuQXTFbeXjmnGZ4jdR8Da09HbXVdEVUgvDrZmcsy2ae8oHTO1wVzjMpyLbydwnCmx1bD1+D7b1Cy0QzP4sr7RM4SNJO9Oeojz3omAqpZrhAVC79oXDNQ+BJHGD9mWlEssnyZ+jA5TF5GvvAmVx+Co7QQHg/87doPJJ8qV2hLKw/Um6QkWofPGdoSJYv/TuUBGoX0OHqAjcr6lLVAz2V9opKkLhC+8WFUH6pXeMsqB+qV2j4j5KSwD379w5qvbiV9Y9qgb719RBqgb4F9xFqgbnF9tJqgbl19FNqhvkL7ejVA3eL7arVA3Kr6WzVCfQX253qbjf0mc6Wr/WDlO1F7+CLlM1eL/gTlMA51febcri8IV3nIqjmg0Tq7RU4YYozNIj7EOal5m/dMwZhc+ZvKfASHBpwwX/jOoofcIPrMmGD743VCXT3zd74OcOY8JsUJFRxM7skEG/sTb9fa0H3uw1HGGtI0+8cPI3RKVKdd0R1vCE8SgwhSv07yNT4LqqGVcaB6QGlg3ovxFoW/egyJe7tfFDh5ACuJJrTtQaPQzqZiEuzpbmt3ShYYGosUvrqA3T+JBjGNLagsAN0NSm2YgFTrxrDVfOEBJWx+P15YuLnq9DTaiguZzK0qWakKMcMlkMQ0fUhVGMzsnG0cnFZi/UIXbbIozqajHCo9AbJlyh/KuEMix5zjLyf54cXR4l5BcpWHJWBWRg5bG5dAnPtVx4X5vDSBc6GsrXZfJW5JJmcb1ncIoIZqDm9tHJBVyy+VoeFdXdXZtU80MyOj58X1Aze2/kewszaNdhVxxqOWdXgUlHSIFR49swsrvTq6rR+I1SVV6o3kqwbUt9wlGzwF30phVLMRStl5oPVw9APErFHWWeE4u06xyT2M+jHl6rxldRwHjdpXrjRYysw49Iy+nKQn3OFZ9TtcA4achT/PHsZPPee9X14WAwrN/+VlHWq4YwjrXqhK59G2oPqWSe7a0IvlcnezhFe1I9o8MVzXrx09HwnmmrWNgVTLy9t3/P1HvDZfw9j5x6b7h959Q6Y2xVTHhxcXJ6eh5NvcSm5WJ1jR7O7NhV+qtXa/D0qDQXnybS3MHbe/s7Bzv1PTznc7bK69ZXZ69O0ZPtAyDi6EC0NeOdTaTyR6Oc1LwRhJTQQManQd7e3iacCppINd3Cch5gcGzNWcZpH/y88efkw8zM81/Pjl4fRYfbhKec5ugV/mfPRTX4K9eE/Gw1wo669FYVwGuGcc56tfRmbJUQ6shGqId+R0uy0nx1nPTKMlJMdi6ITA3NK+6inUl/64P93UGDhT4xaKojZioEO1EoSwrRbfXNv0It+HXjsHGHfOjTWlkXvnYwRua5OKAWybyl0NTm5a1YWZwGpobZCdZB4VaxH/SeU9PqNk8H0mduzvrCa2px4FyvsXzBtOuIyqqZb1kU7fSwqKytu1a8YJ8j1uj4/F09zshQNWWmSsPsjDVaPtCogIzzgopVhdShYQLV22GalvrX8+mDEMvowlr6GA/awOuTwu8LlkSArRrb6NtHIntOq7iFZZCzw684diBgd1O/J34gZvvJTvJ8fzBIhs92h3sPQJHPixV6xtaP0BnmkHK32FDfnJyf4k6z1rWDgvT70BEPHovbchD7S6O4e9RDA4O4OcMyFIRODCSJI8VcKQvlWi2mMmNYIb+SZooKHbKLNBZX9T0bfP+FW9f2gIqpr5umaHDNAPSYnVkPIVdOPaKmpphNuGJsgaUpxrmcbmGt575VLaxs2toeDHe3BsMt8FNwMe270LM+EqfvchUTq7O17elBun8w2El32fPt7aH9kKV07/n+DqXZzn6WTR7AID6i5Qo2wwrVirATPkWaXZwfnb2+TE7/cfoAFF2azarxctN8Cn5rQVy//3B06v1Z8PlNKOB6gSm3yxLg4TdgHS5lO4jd1mCQ1ByEUXAzKgnoJMJKRVyTNfvnWpuFh/s7B7s1QPGYvvqqVbBLVDVACYPSR4s5VOb5bM3wYbXA6NpA3su4goIKDpLNFs+F6gehFNJKq31AhZyzE7LxDjxuqqrcGWXdbVw03HGoyy/jlPuwN3ieUOeW5jco0lZ+q+VyIqN5XcjVxsXR680EbSowskNZgK4kUVqaGVYEpSKrpSLBko5LUzm/3WUvOTv3N+VM98jJ6wsSY0zIBnQi4XmWUpVp55Znc8rz6r02Yb9PGLY9SFK59D0t0B56OKsE4VzlgeKJ7+pIgdjdOH4NfGOBgDzgiISBuC1sXft08PKRn/h0Ro60LhUVKSMXTN0wRY6PHkeEUpiVpd5UBIBZyMbxJnYsbeL37uIxwEelDli2yoU8iSdy63jymHU8/uu7ix5581e/nmci7ZE37/5qNbKoWFiPHL/+6z1rHrbOJ619LlOat8q5Pvni+2m8vHm52VKaLHtYSfF3zm4fg4lUUypcvb0VYxNPpcnGm0/YzGci/VRkaX5VCr4qxbELZ5oTO6NF/d0jcG8w+mPw14ZCDtUVKK2rq60ejk47HxbDxvnCwXnZIxegupy3WPqY5nwileD0QSgKaa7AeFwCp7u8tZd8DtYeWo3N7G3ogAS6NJiiQvOMKSzuxdsZ7tuD7UF/8Kw/3CeDncPh3uHO8/8YDA4HgwdjhS2eVokW1sxdAqXh8/7gAFAaHu4ODrf3HoESlDBOr67ZYuWVgY5axYB8cQIs9wCQ2JFbqL69eNi5ECGVlupmVRvrEqsY3rAotIoRluf2gdT9VKEVlReCxNVw+HEdFUry9zktIgiuTbG3PXwsJdiHQgr20GyjRr4gDhEWMGPgum4sX6jTsQRW+3t7O8881ZftlPUI7D/RNof69tYyd5ZStKq6oCla7Ny01fvtwe7SpSkBZs0Up/lVLbr/qRnXtZXFqapy/bqsuLj7FIQmKKEKfLqImjNO4gbIsPbFjLp6+D3C4yBXdBD6AC8JplZutRBrL4Us7DB0OqOQpara1N3be/HDD8+Pn52c/vBi8Pxg8PxkuH18fPQwaREqXKxcAkbBVRNLyLjkUiizEUmJn1nVCRzvpANR8OieQE8vLsiPkrykYkqOoRqTC/pcJOSCseAtnXIzK8fgKJ3KnIrp1lRujXM53prKYTLc3dIq3cJyTluWMPBPMpV/ebmz86z/cmdvp0V/DNboP1Q+OyP+j7FcdTBdPRhNrDByNpnmckzzoOUJtvSFRwPJP8Iy/UTD1AP/JVimrepkzgWEff3uME0vLv9aqa498vKvF1SQF9bo5DqVkenas+ZLAobq0677F2OV1jB/FCp/tFl610atLeEnY/YF2KANRB+Gy5/ZnnR3uqtVi6IEYzup01NaXLdzP+QhZpXhZnN1nX90f95T1vlHJn3R4hS6+yi1cDHxUKaRVsFeUAHHwqoYVtSCIHEPaa11ASjjUybDK3H9R99BiGErf4zYZukMFMSqMaOF7Ozca3tSudtj1ddlUeQ8lOz6pFL53CxWVUnx2AvI9j2nFEYxWu+riC0imDBXaSsw7kngubyVfVfdKG0FWobZ13U3zK+X1rYqRFZE2Ne10pRusjbAUpkZOQJbgDYABLXlimu5KlofO83o7OINELutMBx1grQqVnTgdK7sMRW0UVXMb9uPgDJl8iouJlKX2FJMuSkzrBmZUwN/tK+i/pus5VKsHZL+s51kf7h7sDPokbWcmrVDsruX7A32ng8PyP/UrwFXmSX0zsoYn/bYiFqigTQ9X2cOm+LICZkqKsqc1lq3mxlbWJnKUJpGV+vH3jBt9IjlCqVvCp3RdA/vSHMplbOZe8HsbXcSRfDyKnkZ1dUeyDk8KeuZYVVGDLpXuLCGt5yDeI/kd/uCfyy1kaKfpbV1KaQ2NF/Vrlo/h+FRfDVTtmAtPLi1wpzQd6HRtChqqBxaoo4ZuRby1rVssajARFKRX87OYwMHWyhWVeBvecbyBR5k3iaCpj/wsU2757uD3aU9popNrRKyQmH1Fma4T1b1/3bcBdOKpJWDp1NY/a1kY1bnue6Wbk9zZLrOjuR31xYsZrJe0FTOjl4fRc91Au4Ooq0jNYUjl279UDIh9dURV+wjLXHbGUlevwtf3N+3CNOMnJpnpVFH90J4RldNCRo1DZ+2RVEm55SvLE02VhBC4Dr8hYSAJqFz5nqLxt3ba+2WBXl5cnRu9/8RNoGvimEi/HE6XEiQWVV0jfOf8ro7r0JKYoYMZsdsha4Un+vYjGkOACXf1XOZYr79yf99j2HiWzp4tq04NWo9ys0t1+654MOMW5DiidoI7YQmfsGbqbyjzo7CXHcY8upkrwcJaZsES/IwpxIk5CjLPFCT0AgGw1PdEOMFyeUtuJR9YH4dRDzxqfewYh0FbBysWUEVlCd0I9P66bWhBb3Gnmo9gs2RZ3Tnam+4vRkQrHK+q3NOMxPSk9tIw8NRWeoSOvPcBLOXEgWhs1bPYQL6zWKwIDkFFaMfrEQ3oJeN/6I7LigYKRCkMvSYy6rELgQRsnvDLeXCmZpkw+ToqS9YjyhmJ8N615tPYAR+7jTKz59B+cckT/4xeZNfSMpkEH3SVSz3os//fW+rLehr1Wy1hTfXudufVmxwoQ0VUbvj0+MLeDf53kuozi60Vl9ut6aCSaWotp/XYaAV1YwWBRMsAx8bqLpVMMGcUV0qrEV3SzU0kRQJ4OrCIuspSDOqsluqWC/U1pljBWHdIycyvcboCkO5ABPIbvz/LMeQzg9dkLNQmPFT9v3dyUpPojxWId2ujkQ8X1c15Kv9esR0WpRJqel0mSMb+slnV3d3qT9nypqUkD4FZwCuHkS0hMbv7h62artun4bu8TXLhxs8DVzvbWxdH6lRFynNLd4TarUlS6FaX/tIyzqEPygxtxLmAR7sxbe6Ff9Cp50bpujUKxqVme1e173QjXwAkA6D8aURpqsYpmVNsIzr60QxmiVxxu5jr/SNNNUFuM8CJhtTWk7ZJnTqsodnyrSelNYw36DTqWLTqLsAQbrTPAfQ9KarcB/KsmDPOJLKPH9gxT1AFXuDrR5XO49h4o9E9/PZIWgxyEkkNr2U98bIXZZIVU0ed0Yabwk7yPq6vstGCSNKRV4z88PZm4ua9QIzYaXY9tgV0NFMYUSwjlzyi+ooUv/m9eWbizfLLsWUyeQLcscDOH8Wl3wdmS/ULY9AfnGu+RisL8Q9b0H64l30Fshvbvov001v1+abq/7JXfWWrF+iuz6C68tw2VuA/vxu+7oTYEWUX//JjR1radGmOjPOwKtyCjW5nTmpOPKQjcAfaPeKYqZUQnt/Muiozjr/iKv7afBxfm7UjeMGYkc60BHNVuOLJJbwSs/KRt9nPVxjzBkVXEwnZW6l5kKWijBxw5WEckrR8Kd+yV2EvcKYc2dtjsaMGqy416RC8REq8KILT/CN8KKZpBl8kjRdFbOQV0fH8bSBAhZxIY2r2Y61q0BQvn1xTJ4Ndreh93E5nUKt4kNyStMZkalhhmy4NmY9ctAf8yqx2tp7m9jt0mm2zstwK8mvIer6n2TGPtCMpXxOc2wCqMmU33jfOaxpZcggn+PEFJq5lcK1ZObCsClTCblAk5LfuAfx2sv51l1n3jDibFHMWMfhuf7r2mDQHwz6e6fw705/e2etR1pf7voG2XffszzN8r2+d59D/JZLG4YdHu3uaFe/E/yDc0l5vQUM799KmkMpqjBmZCeC14+iBuRc/ZW/qNSW5JCuYJU7RexSZtCvyZq69eUz0j7f2ESudX/CplAT/ClcD3c5HeAKSZbg6aR57qcG1oEmKq1O3iCKnszl0EC1oOk1W6pE+HLIuvG+OHS5WN3SKpYyCCX0SH8huK56bQPefxC+UicTOuf5qsLN31wQHJ9seJ1NsWxGTY9kbMyp6JGJYmyssx65RQdZuwAGPtmCu8zzp4P6M5chad0soISuV4ILFamcb6nb9UVTS+VX8l/0prW210wJ9oRUuh8HnC2ADYadoreuUUML8t1kNxn0h8PtvruPbkL/tL6HL2OF44qMjlB3Lek/mvTwESGfaz39fG7vpkwYqXukHJfClPftV6pueWu/rrCmzvo7jdJw5OYZOW8D9Kc2bCoV/x2fkE0kuTCyUkwrY3OsJM3ApGIKKrCCHOON4kr+cc3IROa5vLUjOwOmXlSVbPh4ErZ5SHIsPj+nKVBU8A9VTuRtq+3sGYL05sJaP+vr0NMD7+fAGeNMKReHkXO8f2P19uP2iXGlw4Wr5ISc54xqKCRJSg1OGXvWyIL5PiWQ4olTnR5f9CxVCyULqRnhJvKJucL1bS0c0HzAkbTain8tPl9WYA0HyXA3GdagbXP109gJl663XsNGeCEVOc5lmYVbG3+hhBkZcJXvWvlCRaKcXzMyMtvJnGW8nI8Sy0w384rb2ldG4d6+h61pwh2Wr+AXZ4JUxnkYsctIr9sKZbFkRd67lKoLlkqR6UohmlFNxowJglFr9WXb2d6LwzmMqUVg/nR5eQ5/3x3O8cLHr4WkGfsSduyH/OYgf0qVe9mjmQlNJDxS1tJSuRcxiv1WMv0EsZh+oLHMFo9Rzz/aW+siri7XAJ/ArE2iHxw8uxtEVz15CSB9Waw/5gy/dJY1Lve9+P7E8lySW6lcs4cW3itYlUu4mtf3rc2GBRYc6NjzsuO0Hu7udC/VyuJg14+cv68ZCgtdsGq0Bse+ciGEuZxqHx0S1jLNOTQQsThqKAcF5U2hpCj1baHC03ZFeVaFSaKkw+sYIqToa0NFRlWGYCDRKn/z6B/9twhZ/+ykahQilf3l2AHKpbC/dlRU3N5hu3v7z/rs4Pm4P9zOdvp0d2+/v7u9vz/cHT7bfUBAi1+kOTMzubKFqq0FTnVfN3zFwHPFjT2PICo29HIJfXkx/LweHTH68fRyVB1JoykzvivKj+xyBI4/ax03i9t4Tat+x9Qm/Pmbi8tu6q24ucD6K+7KCga10u7HpvyPKBqipuYlhPLli3rg35hq9Bb4kzpqGBcLqIqaVvFzz4+O8YX+JejIrg0uOZbzgipvdc5jkGkY1Kp/kdIQZltf1yQe1o3qFZIZywvnuc+YYanrCaEYNZqE0GtC5lynUkz4FLpPuU3dXkk+p1O2NeVLF9D1NFZswpRaWQ7wWzd8xYrx1mnJXF9bY5zLaVwPbKsBuy6k0Oyzn+s47bIHewzk13qy34fx3Ue7x/xzn+0O2scd7g7oP1r0OTCeTvZFS/iEws+N2iH98JfHiL+arAujOuXlSWSeI6421JS6I4rh01us1vcNTtQdzLA7qMdEr9a4B7jucqwNwXivGiE5H3tsDZ7Vvrw/Jy8MEOfl+RpniqVSWcUSLhKwpi9+rM9LauY0FOhWzDWHHy+wTSyyhktrmnDFbmme94iSJbT+yCW1myOnImVqM4xabZMPYZuEsWZUZOBBouHOIZVCuOsDQs7c61TbreDGpMQqdXk0TEUCBM6PpZnQUsGtBtEFFdDicBP3dAyHv2jpIEVH2sOnW8o053RVtaYD6+AseNdRrWSV2tfrCAbzq1p5USzLzn2bI9RxgcQcdOAekaVxHxTJ5r9b6wgi0aolEXTe5cZyLy4rTVZmBlb0OjtpEqvG9hW1Ll6/Om/tH0LOTjpOvqVNqRWGOJ7Fa8Hu5oh2SyYz+wj8VaGHaSy/Xro/78lNOmmlDYFNZk+yXE6ncEKxdEYF13PLXP5LMKkt9FGNGDDKq1QlKwCr1fpoulJrOjeul6GpNRMgtHXLqtV+/iiNuW5H6oXO5TRMNGbRkQb5mWRkwcXHku9HNUT8W1VnNOn8mJA85XrE1jG06oVFgmXx+N8HW3ZcGqKoc5qSEcL8/QjSKYXzpp4eXzjyPUFCVOj/uSqtrtXCyhIcGgCA1YO0Si2zW9O/caMZNux9Pa6W6m1Vbf1JxQ3klmqxvm4wAwczTgJ8PZJJWK/QVfU+j8HWDVVbuZxuTUoBnUB04jfaEhIl7m7zpLcCb7wXxWIV4qH9MtQLOAXaOM6VMaXc7YF2BHJDKTC1oFE+u2EKAppNo+QsnN7C5SZPJSQGItvDIHjBAPvGzZtJhquCG2th364U9IUswRtXlCbebWGvW6nkgSHQ+xAVjQvc6v6nzTh3Tc6ZX0kUSaNbqsSoR0ZMKfs/HP6pdA2ad3jrmFLOPxGJ2mnTg/Bk0a5xAChO5E56exa6Vo6om/kyuaUuQQjFGyseJc2p9gFcXHDDXYpgNQPoDs5SoSQttZHz7igDqaa+3wT2R0rGUhptFC2SH/ynGrHQ4QcdvJKcN4OEHxxCY4eI4mhqjRgpF95+czwH4RKIuXM8xrlojf3SQHV3+048VpkM0eSBp8IufN9VUcBfHYdiIq7/e02yY1wguOFTg+9Vk3W/YscFmVD1o25vsMA3yb/oDe0keinSFRaPbJHcTWd3BTq7W1T+CO9wXwgypLKDmFoCfuwdfxeUTtrNmaGQsxLLcpemEp2BKD3n3MRsccOpGybc+GvGyNsXx5rs7W7vWqR3hvu7SQf8yYSmPOdmkazClbAeYegqPxM/Yet4A2zpDeU5HeexInCUWnsbdoqMsLJ2t0XrjoxkKnzAcZV2HIa0727vtBl3e+deGq1QSkSUsid1Hz1iSxOrgQekMD3rwqVQXKrlitA+bKkby+znaTP0I5eYVUNyTQ7I9xVx/iMoC0kYEY7SUMjcvq+gTwNhHwqWurt+H5BNHfc08tOfDztu+nb2usgaAHj4NvrojglK0tI7pqY6u6MFCtRDY8NIYMTaYlW5pzlxJWmASk1n1dnJxWYvVgytZtcC3u3MqbSEd/aS/3GU3Au61TPhMPN6pgVWGy5SE6mzVt+0Go8sUPHLK7hTWaBN3tAtO0FpLXmnTAgLvmrN4Y9mhjBhPVNgKSYA/+QdHBDZFX/g4kdQtNb91JkJjQjy2CfzOvrqI+WyQvx3rXAMOnLn81I4IwAtcHnDlNNQaFWlBsIR/Dhx4Rddc3f4SPfHlJnxo/sAKDdsM0mUCqcmPUGhl8oAWtU2gk76Ua3kaErsgqhueAqabYhacU6GeMmRl7wjPdBuA/l0K2PakLNz3QOHuO7FFeo1mGO3XPlWF5uNKD1U2Z2+jVwRAWm3UgXneig5EMaoucraMRkVWrq2yBE2Y+ZjOiodqSLYLRtXVLKkHME196hjpJ6LS5zQlI2lvB7FoQAjc2tVVzVqhJog+tEN4ZjFlW+MDBXbMOv4t5KpBRfT9p6lfF7jro4L3JZd/5DL23W8vcVbW2xuzJRCR/9Y2i0FJT4asUlnEzJCNsEb5RFGwFiWscaHtf3998olT/fIyO9j9xNqMbyipi7nHYfV/kGNAE64mMXVKoO+fCdq70oVkPXvkbPbAgvE4c6gmtyyPHfyL+BTKGlkKvMqjb4uGqM2QsRImffpVEht7KHoQ7uM9Lxeyf9JXg+57u4cHfVCsQyS8+nMbAXi9XkGRfQ69MHD2Zv/0K93f/qPVz/uvfqvrYPZmfrH+W/p7i9/+33w19pSBNZYgZ9p7cQP7hUDvzWNopMJT5P34q3vHMNCeBVV7PC9IO8Dcd6T7/3F5ntByPfuZhM/czGWpcjwD1ma6C/uOjG7lz74v+KRyfekFMDc78V7AUJ5TovCCh4QU9o7du2B5wyguRTcSOVLrrAPphcP2eHxrQLToCSOJlBhw1LlhrPbnqvpGDJXNXm/5hFei4eWirxfc9ivJffC60ktFSmY4nNmmGrBH4/tUbkf/hrgzWUNE9Xo0YkcLtNaj7xfC4sGf4VFW3PY+mWLCJG8F5V7qfaKczClSmqYNUBEYApoGo+hflyjGyqGFHqFYe2NhgLkjTBzK2EJNagc7tI7TJKg14vmWtaGRTArTMLktRndpuiYy+emx4P60fzFSATEZRVjH0XUu8yQSZnDt2cX5/YAj4f8+/nrcKKGeP9kre11AlrWxMhEqluqMpZdfUp2e9W6GO9gIidk9JO7FSiU/NCOnho+306GyTCpe1U5FXS1XTmgNMS5Pyxeo42/4QX57e1tYmFIpJpuUa35FPIU9JY/XvoIXPuL5MPMzPPNyhy5cMcKKCG5a3Li39Ju8WnOp8IdaKAbv2bmRS5vMWwZPrnsgjAuRDujdl+69IIunNqt8eqEFmIpEt/tf3wdUmIFU/FFL80ydwK7xB/L+V4ducmpcA/HzuJqb0H8jGBqbvns7y+PXiOH/dbnov8bfmEoXg9zTVzpgYQc5VbJi+rKITz+7tBOm/AMyAqf3SUjwB7B1LjHtbpEGBLg0Exk7tIbZAAsGgQp2p17MNhOhr8RJlJa6DJ3IRpGRmIeI2AalvAvjF33yM9cMT2j6jrZDAT/WBCGRSBx2K1oxwDN26EYtXCd1u5eOsoiwmCFzpA3zrJHZO4KurgTnQeGxqwQEagTMeU3TLhkPCwoDRlFznSo6lj5TddE50eI3P6ZT3gN7M6k9vsMni7jxmeyP8a8ce92GDjVLx0mjv8xDOmNnW4jZ7sed+hF8gr06nUXLffm4v9n7+2b28iRPOH/71MgtBcnux+yROrNliIm7mhJbitGlmVR7u7t0QYFVoEkRkWADaAksTf2uz+BxEuhWCWZIllu2c25vRlZIoHMBJDITGT+8hR95AlJjaV2H1bVdYJwwhmeEuEJiqo9dPCebxroJmHyBkIDN1KO6nOKfV2cT7t2b/B1SKxrj6YHXMgNggakzVAmFcFJYKz+08wTnjoPJZPnBqUg21dZMmkgFU8aiE7u9ps0Hk8aiKg4el2X/FQ8I76aKkPn2Gv2yjb7LNIS2DVyCBqvTiSJG2hCxyCWuoSipy5I5Xu+wn6Ey8u/sNtR4NM2Tv0p/N1T4OZBcuYswjlEA7EHMmno2yoz0XcuKsK4CQHvJu8MrUisGm58k6BisgC/OmKzaEFb71tfMQYfRRZ72/maZ5/54jDNzaCYxcRAJllWwenzhcalDH7FkcjY/AJAkg+Uni5ywGWzGOvu3UQ2ILaq/SvwlilTIpM2vGwu2q2JAH5hXAcM5UzRPLxgBza2qR02JCmYEfIMUi7B9i4NraXaufjoixb+V648/P4MXhZwmj7xsGB1uEuOpgOEma/hAKkbPqXfF9LlhJq9IXO7+wl5Axd2VJPhIWgcoY9EAkTcHxnJzMDo5OoMIPqha7n0kcaJ4IBIlod2/DC+04cgJt6RVyo6eUCi3MlRdwWvISTMmV/Mq3Nn3YJYoRE3blSefw8R+iCZ3HjQWjyAZOIvDK0VzYYADMZwCMVNEhodTF3xgws0ItQ1pQRYjAsRMD+uq7mddalmigrcuxWUFmhHeba0AAX4HiEYiCVkXuVvwb68QKJ1KcGz/aWSDH/42oISx99nsUGJoe/ZjAtZ+M6tuRJTZTje1UUkrBZ2iLzulcCHyJ7g7jEdDGUX+QsgFgRyG4t3he2RdWofFRroxEba8zvo+OPvDfThsoHOyFB/Qjt6swK9yPopjXtmmPmbs6+bGqybGqybGqybGqybGqybGqybGqybGqybGsyHwzDT06Bo5+aPgiuMZDh/v/ZQhg8sfK+xDIduvQ5mLIOLUBLiDx/NKLP8vYczHEffczyjwMMPE9BwXH3DiAZlMR+HST+LRTRypAhsRp25Lay2KkUzIIrhB/1KNOP44+9zS3KxBMA8wS+HHqu+xWvqdFNoclOmwEtq3fRmZm+ssOnN6vzioxxd4Mm1dLn78EFYHgtQYJKhFA9vPJdaWwRbC3Jsc7NhkGfv+VdO//Ko5xpDMoWH8NK+LENcDDGjf866hKcDxHgImAB5zoQkJAmh1y1dKRkoRMYTVeHItXuQNtv9ubAQ67Yc9g8vo2nDui3Hui3Hui3Hui3Hui3H99KWYyJ4ksXz4BAvGsizMzxi0MyQKLctsrvHByCC4rTeChgXGLOT2bBX0XSvrX3JqIj9m7tNI2JeKCADb+zqiYvmvLDtQdFEEPeU4ipr8pGmEyKjKrQvV/skQkx5Z/QB9Fci4X8m8D9ggMEPPE0JAISZ6Jz+KU9yq6j9LwSncnxblvA6UMJ+gYHn23Dd6RgzNRPerjy/KyHNb7Xg7syxnOIRkQrqF+C7Ltt09vdf7b9iUwGDCiJBjLPtCqV865rCrE7HjTGDXrAC4VihbOLu+OWACWivXr3YuTj1qtAU4Ht4TCzEFDmzBYdVw34j3LX7ROH2vFo+TjOpiKgzjFR4j7fTPZe8TNRlPX+5PHPEacE7UdutswzN9e6Sq9AxWUy48MA7yaPFdSw8jI+gu60+r/m+hVoefAslwimOyw7VbdYnTWMZzG2yBM57XXdsMAXCg4EBjbKxQgOr8WrAhfFymoowzFRZIyLIyVbZpMJqt6iL8/LsNOK3OsFuPquaMPCfq9awPoZI1ZzwpBkn8f3cZqfnp0Y/xfVam58XW5Q9LxM10h7eou7EG8vLVJzqYyMYAXQZxsc4gbBFyrNkwDOWiGl5x+VfeZq/R4+Zv+Bnfv8V7KNwHFc6QJjQegIsRuNUBW+yOSBRzMcTzFy0jAubuVKwNmeyPUIwJOkR/EcknQBMFBYCM2MsDGiqhQrjQDc3FxykLCEP4JQx+KALMHoycn5Wge1c2/PUl8pmXGpmSaLSZbE6cr51ECjcaS58lzu6hU3svdJufvc83Rbik8Pz9siB1Zt2NuaxvDH6XcaM1wHjrwSMv+No8fetJVYcKv6O48TrIPE6SDxXhfRLjxCHEBh4SMKb/iL41ZMXfG4tPn6/g3UoFU5TkvhCXzero+9UuREkAu0JWWqlodzX8gxRo4iCa0XSP8NRIRfZD20JMWPamtt8LEg0hS4vcWDmLRUSE/GIKhKrTNSlNOxaFaYqrfrD2/3efhF9oJ/RNKk5XrfZsWepcjVBPWkqZqM1frvkx9ztFv+bAB/EY0JpLUcV6n7omAoDZgrhCQDLuSEqACAHu4M35O1Bkuy3+62Dt2/77W1CWq1W/+Dtwf7+2/03b9qtOJn34McjEt/KrK677cgOXxKW4xA8ljsiDJRq1ZW8/7a/s32Q4IO3BztkZ7d1cBC/Sd7iZC/uH8QHu8XnmWDymjg6LlaGAH5aUTt4yj9NCPOQzIIPBR7Du0mK2TCDqCS3W0pCcuyWICnF/ZRskcGAxjSvekc55kDRszTi7MmY13bPn7IEloYN0YjfhwxDywK/orbaL5NENKEcpYGGKe/jtCQX8+sqRsg8nnKCVaXZd6UVImCAVdJXlFxKY8JkbbbRmRneNpfKY6YhZe6wB3pCm1RYGw9C2bsCZGosDDNi6OwLPkbdi+PfkJvujEqlRSBCm0NK2k9JDqEnJ8kDwOfZIeXW67Ke6UxwPCJ+4O2oVaN/UHlFBFPkO4cXDfP6+mVdYDUykiysGy1tqLD3VCbFFmz9rSOSplhsDflWO2pvRwez/YEBfb22gP0HPtYkmyiYnyx8IvGWDdivVOamiu9Wip5oQOFhdbnWZXozzXvfaINnDq6f1ZzC7ZhC093yPbK9vdP+Zs6RC02XbQFIfLT+gbNDwy1merJNJ6ThOtCpES5+xDxq5U8QEJfwYDSHSEzGDZRMbocN1BfkvoGY/sWQjBuIZfDrf2NRPvNiMvcLTb2WmFvQ4ixhN9jt6CB0Cor+wAn6AL18F/EIfjV+ILrgQumtj04eSJyZH19dnLz2rXy+C3P76OJLYRqksBgS5cPE0OWpZH7v785tPRbC97UUkjAo+oRpChkUpjWgBddNEFbwKZoS6PpXDuzQWHCt9dARFxMuilBWX2GzfqvSs5qUzctncnqBw+rsr3Cmx67ZrfKszfhNz2RrP9qJDvZbraj9Zre9Ny9/dDwZYVlbU80cGh+cmzEg4Bts+4sT24OtwxwVqNmEBqLwMRTQhfRfbM65S1wYUDYkYiIoU6hPGeBtw8M0wgNFBLSp1uLyfS5MU9KYJ6QZtrFEFujTubMSjTAUKcSZENpqN8apgSGMR/B2Buj5SmDvDgP1JsL2Vaj9+/v7aEAFIVMCePv9lA+31EgQrJqCmCaEW9ut9u5Wq72lBI5vKRs2xzjV9kjTCKepJ6RsGI3UOC1fVK14/21rJ94lB9vbbf1DEuO9g/0djJOd/SSZu9+666PRg2NQd0mcFuQyGqx70Tk9v4pOfjuZl796kyk9U1UZlc9kbsPr5+uHzom7heHn2Ye8jae5D3iPXYWyMwyCXz39pD1XpNBNUf0grY+zf5SGHozQCcCizhV7x0PPHTccoslWsBWDbrhjA3gXmcqpGzf9hCY3iA8UYUgqPJUuJm2mQlRJkg4QZn51NVcTatSM/qDxx11/AnjsMuTmceXl7JxhXRXKmx0h8NTitoPwsBhmAAjf0MIQysfrIWOpL3maKeL6IOcqckQQ8YZeoOI+4qlWyiaTwEhsIri2pqAQnCp6Vyg3r6zpAr+wT9mWlKONBtpopvq/M0mE/t92K9L/r70/W9Sl5dYDIInnOUwzkQjChspfUW7P6LEhVWI665kUCqCCLgcOKta2wdAc63/1s/iWKIQZTqeSSsQZGvF7P+RYm21+TdC99qe9UlDcrFFwlNBHuE38F8ZG/pj5EakNRxlDQmZyQmPKM+l7WpWX4BnmbEJ6kg4Zhrh0QodEqh5Oh1xQNaorRgo5NPbCQ34ybwhoegprN7NgBu1XL5hpnDbMqBwhz4VtAIF9e1dbueiL6qBJth/SVWhrVQ6fFADqbFVU3jfOyCYntyx1OcLbe/sLip48UPlVoPM+5ynBrEqm78yfwja3dIBwLpawN0HpyGp1trkg5fonyoY19mPS2yWIAs67T6j0H3VNlGY7kenjmg0wuIqmZDUPFJns+LADJ8lbEQuSkjvbhaUz0bvqp09dQMMo74uYjyM9J4keJnEEOfyLilphldV3tXztNSjoAIcMKdUidxo05aYrRiymE8WHAk9GNDbdymV+R4Wj3uGUJiGulHbbRSaVm0+b4HcEZSwH6LU9hd1X86+45OJ8fD/sPZYoY/AURCp66p9cXn667H05v7r80r06Oe5dfvp0teiSZQAHUxdsUNcMX7BEIXPHqLKVBgVmOFMEj2s+9HqKVZ58GA+e36A+BV4h8ydvY9RH+UHPr+DnHfiTzx9++/3tx7edXxYVrb6hFB5P5hDuY49Dx/o8YZaYZ3PfE8lvDnMp6INgHvT1UYIWP3Bblq+I7dZ2u9nS/3fV3j5stw53Wr8vemXA+Zzr6euJG2+zq7hrLhnqiIpzr918OgOURhPjY+Vff+x7zibT/hxcHCQx0EtqRHM7opAGA7BIBRhxbWZwnrqGXNp0I+nUvEYbA8QouLI5vczdDEpxSTFXWxaQr0yHVOG0aGOYp229mYaYMqkKLgfEdaamX1yh5X+lWseFtfiKzn6unMZjzJJeSufCbLmnaRJjr8JWkt5XlPL7LE0dVUhTZTYKuAu2mb9VdrM5m87H85NaX2/GxzNbFqdp7mwE8ofaxJIXsoQXGLqAqAk9MAXynt+8y0TSQfQNXg0+4nikRV54ObDq4OTs/SOvBm/3m/M/HGhO+lNFelwktdXRvptqy4z8kcHrJx88TvwZVSol6IQlFM9tAGge4knWq/EZ8ejiS6Ea91EGTpnyEd/5CBcEtmovuDAXuVdPHpQw9TYm88JlG/g2l5rcTZk/m7l8EuuY5kaFApXWz2iqTMI1hAuTCLLtMPM4nQN8ay4QGzI2rSR43stiLv7JA8Tq5+B8kGKlCCNJFftntrjZDEcSRAzGnanJM9cilDs/h7YRvF5GuF93heovxRcZvbvCblfvzPWU47m96rw7fb0IK4DAWBMT5q3XgDw+dk6eQ6vepTWReowVRuYtOSDUzrsAqYQpMQ3RmFeWUmGFmk+wCskaKNC6szg3Wg/tDXC4fZt0R3RuTz6LbNnDfVoTuV8/b07yZ5RlD+hTdxHJ13hF2Z3y1C31HEq/ucJb4PTZd95V3R1muBXdHa7H5BzEMRJ4naVGYfA44J6/bE2COcAGpg3HI9fQsrzuQfyB6IWyfl5enGFDr/apCgBz9dAGB8Qhh/SnSGb95kwzWkipZERb9Tchx9FPN8873v6L8YhuL6ZACzAwM4nPtCn/yGwkpY/7NKVqCiF6QftZKDZLx0LLDFcAn8yTgfMs8rsjzBhnyA6PYpzGtl1ubtotRfggxbU9C+qN2LV7E04ZTLYYnTVmBZTIDOsLn0elQ/7v8cFAkrpe/EsEm9mWJHnxlFBI9JyLUN8ZISy4eR69Nd6hJXL1UItReUeFynDas/irq7YLS5Ta+Rze63JE15Ec/CjFC+yEIYSDvtHVCpP91Ver4XiBq9V+8RnmyKIHx0rOCcxvqoXorfmQz9D6/GM+woIkvZT2BSQE1kSqs0zNdMhPZ56RIEWAyoChZ/GgSDqoMSfTDY/kdNznNnVRH6vneyVsqWok1zMkiFUj+HrVY1J7v9naa27vXLXeHrb2Dnd2o7d7O/M/KBnUlBqfHx9HGql6cyQzzR6MFjMvkdBmF15E+gHMi6mSMw3EZQgM6EflA3QPoNKF+m4o0IE+S46QZv5+9+XL6XEDdadyzJlL/kM/fzk9lnndN/QJdkm8MHMGrKZT/1Zqeqf5prLwTFrm+ogzqUQWwysatjl16dQOF0oOULJjPtZUTQSOFY2hFHBMFR2Gz/IXp8dIkEwCXP89SVMo+w0ecbGTZux3GAeERTomDYRjwaWcBbdBrs2Jlh6XquKNLd6Od/f2koPBwcHOm725S0nzx5XV7cJvjBzRmUkQLB7eIEFwRmLh886MTGhVs7/npfBdwcsVVea1upjJl7cFg22liBi7poyAYhZVNYjPjQXcN7YCjOnRO/PJ3Cm3iGhQjRhm1ur/wKNcRQlhe+fNvFtHH8BonOzVpL4+Hu+ZKcqTypHHWFz1rN0PnfYT0+bJcTVMvL23/8TUe+154h0LTr3X3n50apkQMk8Wx0JTd49PTi6CqefYd981zM2mu9JM2MB/v8vHBFJmUGxL7U3tuc2KEkjSMU2rCgBntdcEC61C1gncz0vgnqcyI5fsOsX7W6Z4W8GvM73/skzv6hX4jhK+qxlY533Xl/f9iMTX6d8vPv37kZX7cbLAqxlcJ4OvLhn8EQn/aDnhj7C5Tg2vKTW8Wt7rDPGviWudKP4dJIrb1fpx8sUDhr73tPGAle8yezyk/2+cRB6I4aXmkgck/iAp5WWOXnxmeZnkl55gXqb4e8gzL1P9PaWbV1D/nWadlzl54cnnZYJfeg56QPFLTUUPSFxnpC8qse8tMb2Khe8pP72K/hecpl5F7ovNVq8i9vtIWn+S8pebu15F9otNYa8i9nvJZH+K9peb0F6gep3XvpjEvof09iqyX3CWe0jud57sHrDy3eS8O5q/n9R3T/E6A36dAf8XZ8C7vfhSE+HryXV/jmDW2fDzS+ubJsU/k6xvlzb/fMK+YWL984n7hqn3zyXupSXnW+JeYI7+N0rDn19GE/It3vnr7iaTM/M36SuTM/zjdpjJefzRe83knK67zqy7zsyzT374/jOe079jJ5qyHIZzhSeeFQ0+zb1qyy80aQkq6mzir/Ps+kSPr73o5xpik1nqS8n6z+va6NvdlNZgd3t3+5nEgds1h3CfFbOyWaT1Ra1AQSXR6rfFFQyMTo9XIVtLZY36yZIbvih6gs3szdZziabqZcdfvN8AlM5EJvQOhN83TEjOOBK+Xg9Lv0dBZugoyG30pXuHfshB0H8co77g95IIJIkCbUaVJcJFge5J37SPhduaqXSK+ISwIIt83lXIJpry5+3uouNIYs6SogobYa3GCEPZpLRb2jvbzzXY7rnQxkAvoYLEiosVuh2r3zV6c1iCkSd4tvR3VihbIz4mWzilMZlbNj+GR/n3cSV/aB/yb+A8rr1GtPYan94gP7y7+Lf3E1+ig+iJ+/bun5v6JTl33nz7C123GRpegmPmSXqBbtcTJ+/H8cmcVP46j8tR8NL9qfm3wwqcLUedIEMqlZWF7Ud9Gf7u8YbU74FdZBpIg71lLxs/gN4Jxl2w5Bj2F2vXDAWWYXbyyi3RT65QCmZB94IqRWwb7D6WZH8XERbzRBtV+RF8z4VnXJQZbyCZxSN9CrtE/aLNv5MHKFy5JMPPGRFT+7tGEYwAWl3LidnxPE/HgmI0k6J1k056+nc3kUfQ4BNrbPYz5UyGAFmJKGf13hHhKiwAOSLPZvV1+1oPXJ783Ht3et65/E/DOUmcBVuyJ3///C7rHLU6v3x+d9XpdDrwb/Off8xrZ8ASmxvoa5BLMxX8xYU8MrAEpmpXL6M+KGZcVy/khXLhGcYSYZcsXPVNkL9dC7fQESy/pGwYpHHZz/vNAFOiV1qY3d8bINST3y4658e97u+vzbqHyT6eBqpy54YzYse1U9o6cMh6sxPCRtWjf/xydnUKc8HYbrg0Rf2cyjssKFRkpgDTZoZl2ZgIGgOv+c7VYx7/+uny2Gzck597n/W/CqQHuyzYRB4/KCExHeMUCWLzpY3P9YpEQ3Sz0d64qUhN2vzXxtHhtVD4WpCkp9Tkuk/Z9XiKJ5OIPJBnwNrBxipnF68G1UdhlmCRFNfbXKNWWzicDDnLodkS83Ixond1MNDp9wW5o7Be4Hi4KJeer3SNfPjn2cd5Cb4l0xro/UDvSBNuHXpnswT5AFLzS8R2P72/+rVzeXKdO0VOVZ9fXR8Zi8UWPl6fjrUZ856mBJ1AmqHeoJ9gUnl9T5kmVO+7ub0mrEY1sA/IInrsEDhEL1VDDwcnFHR01cJdLy0Qf8wrBHN9TPrZcBhUxn1FQiGdqxTReeA+G3BCe5eXNsh8FOfGEmi1oq2U/+pxU2kzwLeUROmrekwsMtUAx/oixoqgCb3jJktZ8IwlCKMJJYD14ejTeszdXYDxAh+ASyBEg7NxMKlNY4A/YlM0SbH+JGX6hjk56trMU3QVkmCHNhEmTYnVBeMGkgqCVO524gMAn4EpjE1g70YqAuMl9yUtNh9DN1aK0Y3npKMVZCyI8tnlWkKnF67miUgXYnMBPpYQAUnSDcT7kog7IhouVT3fEcom2TZQnFLCVAO5j+pTwojSRnQ04OIei4QkPTqJ0OkATXmG8GRCLL7O6YXT24rn1NPJTQM+qUlS2lwwQgOJYTSkd4RpFpSgdxSn6bSBGNeWvzbB7kfEb3OqYDIMgcT+NEc7DaY6bB9sR61oO2rvucqgZUzpGsO5nTQ1dweWIyLN9uBMC0q4DWctLoN35I5FA2TotUsmjbMJyHG5XO2oWuQjkk70dpJUZTYoC1LVU20KvUUkoKSNcBG5CsKwOcYpleiVQQIjggw4fENvNK1K4TL0BMyPBgLJ+zXKV49vCuB9yFr/KqhkqBb8iTlbXhzh581VQtD7z8fnsoESPsaUmTL7Bvia0lps9ld6k6cUy2fU3tN5knj9h0pcW31+elHJXDHWIGsDYXL7G/CvZhYBfle1CD43/yuy8vdMZlfJXTLu30/cMPoz9rBD2Y17A3FQbxAPsjUpplSGTb3uRNzJCw+146QJsIWOrmgH4ZQIFXDLuAF0AcZyj8puMpgiKCCyo5knEucfGFcqINzuwkOnmx1RyZhKePrShrTgqb7MlL7uZMN9VBMGp+D0uLt1etHN/zCggtzjNNUbmfTdkAHSSPCBTKQWJU02EGGJwX5JiLKFrVpVmKtNEvTq5PjyNZIQS/eFS0TFK9DQOFMjXtce1uaRPsFDzOif9oLkAk0kyRLOpmN31AwRcNThJ61huUGkIklBqcIauh3ndwxo98K+D127rsKiecZF8gw/LsaKDFcauSsebjeBFYs1Hu1QQeElsZ1t7D3lROBlou+qfNO4GrtqUXSUIuOJdr5OAwvujODbub3b2h/Yr8CDL72tw7Lb5XZyqGbyXcrjWyTIHxmRCizFSdZPaYyOz7umMu7D1dVFF22hq7MuYBPymKdy7qulrvLKjuHx9NioLypd1eA9VSNT8Y1kzA3Mj7aNh2Bmeps0j984tVm5cZ61Ydqt9rxySWlMmKzrESZ0s+xM1jI3NtTTmsGLxlStaZcIJwThO0zTygK/zgTHI4K2o7lT7mp9gCKFV1rgE0KBDkJ1vnNx9unon73j825PH4Le1Vl3Xt4EgYebuC4GNy/dBOjL5ZlePfw15PFwrf3qVt4G/q9ajHp4bdGbu9YGWA3c8+amRAmPs7xeuTgbuGv6ZG5u5vuJcZXvooZ2IkKERYxSym6BH5N2YQhMzSOWEUHf+Sb5JWeRvMAIKkcqXd4GYdE9vaUTklAccTHc0v/aWmh5tQVWG/bM+czOlUQ10ISnNJ42jMViLAJIRPS3rna34GQ/6+43Ja9jMu7nUGJ5gM4GT3sXVuX33hvra145ZdkL0f0Q1+HCZzF4GcGVIPM7wThPwWVgMB2+fh0UFWb5Wmi3Wub/zyu7etPWruAUm4y1LSTIHZWzpkOfaK5h70DUxHZyKbMWfYUnn5ABEg5dp27+myecp479nF5kB9mCpX3pgUCW/htD2DsVMWfMLs/AG+rGFUKCDLGAsKwk4LbIRvB5s/59ah5ujT4dpPwe3uVEkntS77lAV0cXdtSGhQ5zZBraYkLv8gwayqiiOEXd/zxHExzfEvVKOsREO6geMKfFPPqYveiNrtmZrIJMpyV5/K9cCzi5QKIctoNDhNL6RwjHKjO4C5JYZH8xRht+vA2tP+BWC4Z1VLAZwqWB/Ld/tt6jVd5aiytMU5lfFnZEQwpgt7OhW+B8ipAPGzLpFiYwfjVwYUcMYM7BOf13xsymgIcvE3W0364aLBct46o05ABUsF5Gk40462ofmeG3HAvFtzUTJsNJgiQZY6ZobJ6hHuCOxQyRB5Oq2CgodSohtDbIUv2xO6rZpX+S/AVaM0qEwoXYm4ubCj/HQDvUbkxmVKi7SEzg1D55SkXTFBETrjPYShAxAF87COKCwAY0Tb1uwpOJ4BNBsSK+pcNSTvfciF4LGVRwGsyVaBfMh7cLWFF43KfDjGcynZpdDt/x2h/ecaUv4k6pVHo1Ty8aCLu4HYSgM0YfkOR6/0QI/WcucZze46k0Af3iVY7vHU3uPNxE9hc3RmRF241p6yp/uk4y114BQuURndxoUm4iQ9ZNAyVkQuBVAHFrSyDOgoikvmZnEoewjAp4i4vkDlmQHDMOwmnKPZU20MEZH/NMWhVh5J7/2hNoNYgd6FWne/66BEsDScY4HuWRKSNKk+VJKm7uvfb+wSzPYXjmJWINzJ+t9CngpDpj72fOhylBZ2dHBSlUJPvMk9v5KILhO0jrASiVAIsTTqLdCEZhlxfo7W4x4ALb+SuULdxBJ4i954inQKXdnJXt11y7OhMEZRDiw2iQ6cvlD63DAdkpGNvE8Fn+fpA7UHhsn/7G2PbWyedIiKB3AQS+R5c2mk2bNkQrEX1/CT7OjVYmaDzSjlzZfRpwHtl/RLH9jpP1kPAopmpaV1OmI6qm1bvyI2dKEJyWyeFMUUZYFWbQSmi6uufN1CRrAb6Pv9hdLgnMvimr6T7vzOsAFJmpScDnhW5XdrIy0VyoEepA9hGuIDJjSkx7VPK6ZH5kpkCn3U8g9BKFR51Hyapra1qSKlf5CDOclCUFN1vJqSuRMyS8FwLnF5EHORtSlSXGBEuxgn+UY/j/jTZSzjYOUfPNTrTf3n2702qgjRSrjUO0uxfttfYO2m/R/2yWiKwxLrf5RRLRdKbUTMwaIyeeBsImimQMaz5AQ4FZlmIR9rVTIzJFMYDYaU+igClnTR5VjANSYYzkmDDzhgQVHCk3qXV9InIkMOet5MaFIS/NgXVNrLiBYqejwsTFcw4QlvqDxqkCH0TbLGOwbYaEO27LGrfPpeKsmcSltZlwqXBa1ynbvIDhjVrDUvKYFvMEPcmFVl+ZNpFza99mpfiUGn0vufjeLeP3DHI5kWbFgLEJ9PvpBQp4QrC1wZS+w2KK7mmiLTi41eyphsdT82NZfge7rd25w9BarIIMKWd1KrBLmOEp/dX8fPQYXTVpMEtTpQL7nJE+Ke8/7dX8yWe7eK3mWnXlNnp8/3DhNYLLdj3tnHeCz1USby+qrY4YwrWMt95lhHHZ61BB5n+2mnyFy+psiDwxasY+fHV6cberd/vpxd3+62JOxBjHdZznj52jamJmgvyM2wC+sSrNSbt8f4TetHa3AX00Gw4BxfkQnWjniceKKPTKhl4b6G2zT3MTVdv4r02PR2sa2afZe47+lU0mRMRYkv9CI/KAXeoxdLmTaEjvXKw1zD9EjnwzsUkGz5jtVUyZIkMiItTN4phISe/sB43rLskEC9clEPsRR9PJiFRo31ar2Wo1907gv3ea2zuFlWJYRUvkymxeCcykDUpBPV0YROljfVGcd658bNLiRVLrneaXH0cTQe+0uj3++PvrYDmLlw6o7pTjBPVxilkM116QUsEFEjzTt+GMY6/5nPC5CuieVagWCgCqhF+uCEx07xk+brFU0Xx7IY+2WLBXXoYliyit2EN1gNBs1RERJOlV+dIrbmxOhyMiVTCpk5GZuwGMTCYk8SRnffOnmTIfK75GUAICw1mvWlslGzO+7IZWUhvhLx7vnm4i14ANC7CMJKZSWyW29TlE+lJ6a8tFTf6EzAYD+uBHhM+8Gik1OdzaMh8xn4i4GL6O0JVJLVXcmFMPdOwf6/pTJOl4kk6Rwrf5uprIYIqlAuWa4j5JpbGcGFeQGmgQkDX3V2fH0t+jGzGPstuNsvp7zNX3Yq9zN/hJYNN7x+CJQInLSgsM9Twd0aQAkoeYTIxD4cMvNhWiuFXsdo8QOmXaQsVC0eA5AZUoAOVh27Tq/2//bjPXvPcCbkaW2sr4GLP8PQEV91UjkIBtiSDLDPVJyu+rt3n1mSiem1C2G/f39xHBUkXjqR3BbAxzMrBUG3kX91PbkNaMMsI5SLbh1ZQ7uWlym21DZv3tSGb9duHwNQqbOCevALBspRCMsdEwZ45xpASmqT4yEyIor2hXqxmY195TfNIDNr6B1iODAYEexXpWu1Es96/I1dnx64Zxmby/lMvdC82ojoZ7bgQloLes2yvBIYnKCnJ2Xj9sUGGsVwn2wfetGUErPqYU85WYTz3C7wv7JpNERPVumTBKl5cU+0znIIcD8cFj1yJm6Oy4c6FVVsdwfOyHCvfKZpk7MsY0rYm5L5oDmKDYRKdAgNaeK8Yu+cbvLJrNTZlfAxBqeiKdLu0TodAJZVIRu7EKEoFH1L9s25k8mtr3nWGythyix7tz2Dwhm0YEDztbLqu9YnsaOmsMnIYrYSYrE1EnDJSVFGgbqNGB8JswNVCFhENTYGXUEkOYcTYd0z+DjHQjQv/PL5IMslQfhhvggibmVRr+obm78SZAzNnArNVskiNLKqwq7fxVbaqvItKsZivZ1YIpZ093t9lu7jW3283t1vbu9u5Be/vN2zfN7f2D7d3tg93WbnN7Z699sLf/5u1+s91qtcpMrC4k+I31YHekvU9m0exTPqTsSVHhiDyqAwVPa8Ob6Lg6StjKMJN7lYDoo6X50QKKW9rHDPdwMqZso4E2BAGrmw17esCvVlWEOXMOgDFImnO/erKolbhvl1KwVPg3U0QCEYo8MzxoN32PJYp5mpIYgI/sb6+gm5odGMr9pjxDA8oScxy9ckj5UFqt4LvuuLmhHNpkIdqTOuBcMa7IIaqg376iS5IOmqapnHXj7Ocs1ln0k4HNsL806JDRTyhPfPaCMF/Q/FsMSfsln2HjEqaghDfm8PSuBZapITcwEqZoooEg986YkunU7YgP/J5ASatyjWOkiQnNQ+84084qV5pnrfu0QnNrok1r4wFyrmbkRFSeE2szfwsrb3L9ClvLdruzabDmjSdvdiNzweQk68XQasBD+hUlZocN5eYLTLjw2ZiztNmEBYPsYblySanm61G+AcvU5Wv9FfL0oKVFdDSLx6izm+RJyl5wjlvHPgWYUlx4CnVJmNRvyuJ5B70w6/oFcCjoy+VpXszn3hpe0cnd7qEJ7wr0Lzq52/8v+Odrk/wmiMki9MMCTsQrkw4nq/ogvdmOtvejVrR9uLe7MzcUNWF3VHA2JnP1oF9Ipqd5WpmpPPMzWjGHupZKJDLGihBFNqoCcGDugyJjoII8Alg4sESvLBSheRlTeEjZsIE+dxrBdXxHUj4ZQ8ETUXH0ulGiT/vuvieayTTSVy12wDWOqjziYE9ZDlJm7GSvNLUaC2o3ZRD31twFk5eXOGdp7tWdjMiYCJzW2MDvxM1RMu2CE/OKDgACiDxQqbfvzHGhCWLaVk3TqcUfla7JnCAAKChNB78bJ2BtBCecSK39y5J6i3cHe63WoCCMWqzaiv6FvkIAtnG+JU4Hszs95uOJoDIw/fnAgF0wnhCbfVFgOdcrfsuA4QCBm4TICsHar5SaD4bEWASuMb7V97pCEy4l7RuQPG+n5KEoba/ojTwmStDY2C4A8DRjvRQhI7ThBAHjOEuxAHr9kGRMFSS05gaj/9s5VzaxmhpsC0bMlS0Jyb9gT1KBDIhl84LY8/MfpHCbimnjzGKFbvT3rGelHS34p5Y+mNm4Ioia7Lwhe6Q/IC1M9uPdgzfbSZ8cDFrtN7u4vb/zpt9/u737ZrBf2I815SwUYhJus5nM9ydvLVLK2LS71J9MsPMBGMTuF5ym/N4sv+9zH2xmr/RAqiIDLAEfDweUiaKXbCwFV4/g9Cy8d+YnhPkwf3hDWNMFS+DgJMVS0dgibxROkXOYw8i5eWjMpPJJ2igICr8jWMmqQUxo1Sph6Lw58SiG/qN6IW9y196gyAz0wTBvM0Hf0orgfMhH0x634ibiCak1H83tJuy3BEw5o2eCnaDuudFF4QUZXtvMps/7v8ExDUouQ1xPSK8CQ9vAmzSCRXCse7WYp5P1XbdVP6i9TjxlDuLGjTbfXppRyQEJ5R01Q4D+rFnzoP6uuFHtHow0CXp6WWEg6UuPbW7mYQWA8rZ2O7ziAXN+tsbMqx4XjkgLABKCjueRDA4nmrJhRuXIr1p+KOFI6/sCZZPCVW/vOS41qSgMOFk8RysXBlYw5C14lVC2rSp3Ta5g3O55jZpGK3gZW6bGmJmiLUkqzAQ3X7Nl/9Muamjrya19jtX6HFasa9fjR3Y93CKvPZDniGvto6x9lJfgo8y/Y9dezNqLWdiLecY2W/s5az9n7ees1s+Z//jJAFx3pSWCBrEZwfgz0pgbmNPSWBM+OjwTO/ykZ99G8MWZtl7GLq94Ay7YK95SKDxCGk6CSU7cIp8OzCBc+DGwIDPUzZ7yRxT8vbPgbgq6++Yruv2ZC1aJ37OaNful2GrOLZl7t5/Dm7aaXnGUcn6LsL4aDR4oUebZdObFPuhu5++Qsrx2ou1o7jaLf92p8+kt5rV4HQFZbQTEinUdAfmRIyBukdcRkOeIax0BWUdAvpMIiN2x6wjIOgJSZwTEbbN1BGQdAVlHQL55BMQevxcdAbE0riMg30sExC7YOgLyNTmtd/RL2NFPIm7/TfarD8rlESJXbpT/5olqI/MpV6jj2hqVoJ6RJKbOZBCgdTuo4y0DuBIUeMhC06QAe1lvDFyEg25YvJYQwB1AL62ZEIKhGKoKRITQ2HkPv5CpAF/6K8jSIZ6NhZfOeXoMQDmYJeZM0gRQHbTMtGuRUkbCZsAGJdiO2nfQy1BTzIp8y8cmdGIoCtPt9RAp/DSodTOhJz+2izlYyAuHJGmwr11Vk3dYoIzONJOr/pyTgufSwMZ5cX9fONJW7msc6TWO9BpH+i/FkTYn0bVqz5XgCwSTNqSuwaRXL/I1mPQaTHoNJr0Gk16DSa/BpNdg0msw6e8TTNrYhy8ETBqIWYNJvxgwabs7vgKirLUyRF7y6497fOVKIOWgtxtSAkNskQ1fPLD0o+KIlpTHCwSWnt/F/Ybo0lY/oJeELm0EtUaXXqNLr9Gl1+jSa3TpNbr0Gl16jS69Rpdeo0uv0aXX6NJrdOk1uvTfBl1ajQTBRso22+sq/83j2V4b702Wjj6mKZaSDqauAAaK0FIi9I9xzEXiDCs7F1L4gTM+nl5bCq+9UaQZ/nh6dXmCOldX/+fon9cPnRM0EHhMtE0VXbNSQpjWBprfAiX5wJYOk9/kvRwqbAjAxcROj7sNdP7z+19trZ7La8co5uOx1tKW5CgfGuLLwFCkcKxoHP0UEjYmmEEjf5cIp2wswhrFrtU+4oN8TOXHtIRdb9DxBMfqeuN1VJiRxCNQCE9Pmo9sUnBuKYMoB9i4OB55fOj+1D1TKZN/aOZpwLrFMR9PUirhzSYfcshx6skkLIEXRpQQprWn9tNMwqEmfeN/oSVTtvKEgnnOo0EGrzx1xhPQMsjfoyhLtEvNhUS8/28SK2nnc6Fjm12IWVIw/gMgaYhcuyEpZ1tBBsS8/mHAY+RJmoNbQ3MVt5/gL0H64yNcV3C7HNXR3ymZaxkhvfTsr+USvBaWjLPE4rrs3Y28bvy6p9Va746whIsmI5kS8GbtKLjuCQCjv+5lEv4n0IJaD55zRrbO+P3WR5LQbLz1gQ5H1z0Z4zRP9aQMdSaQEfmAOu5q716d/oa2o3Z4wwXj/mII8tncOUUIBvfNEEz+FZYozqTiY5dvfM1OHiagzcNR7+z7uiCH1wyhnyCzoOsq+9yvGDE/nfF784PhzfysGdyYXXnzgeVWPVihmpb92KVhmKvWFkiYJGct4CSL3dtiftnOsnp6gR4i+H+QtG8aJkD+SUrviHBqtMOGKRHo5J9LqlIIXdSMUBGgKHgzzVNgn0cLIRT0ioq824XfX3xg/XjK2euS4CYjKkf/bzb+v7BgBjQlEYYXWjKPB5/kBW5F5/MMnje00Q2BdJoaLA43dGUROOMKLEr9aXO/SHRLyAQpgeNbs6v012Hc6CvG+HycKlu4XB9MiXNJQAT5fIEAOv6X9qkgz6rpT5GPYKAPRJDNTQnlm6xJHkY4kxCaceaX0UOBOaXtJ0EQsTrL5KW7pJ9DhEU8onekYdAKYF0aecyogQiLxXSiSJIH/ckDiTNFGmhEk4SwBhIEJ+a/9TXXsHZBA90LqioKYzb/teE+qx0s8+mvOlZzrWXME9KTdMiwNtOjhA6JVD2cDrmgajSua4HhPRRLsPT8ZL7ES9NjQuiCxxAm9aKcCciHBbWeCyjx1T4T7B4qkc2m8E84UMeQB1CmQUm1/qQA8A0b08+BV4xscnLL6yRHeHtv7nLX+VfF4Ih8JQjS5zwlmFWJ+535U+gEUqjEcjNoIdmElrKHr92hGraa/omyYY1YLXqTBWGqeXdX0KqogA0S4NlADfQAx5oRk3yDJB+oe603jPkWBWMSB2IgkSApubOucWei9+JPn7pQMlf1/jKO9JwkepjE0UTwh2kNq6CwyuqEm6L6x9kopi/Bi4mwFVsEGVKqV2OQmTeslA+HkI2uVSwfCjwZ0RgRIbTz6LM5w1HvcEqTMLuWC+3gS+XmQ2cE3xGUsaCObuDytOCr+VdcPnk+vh9W39MZi0ckvq3CpTi5vPx02ftyfnX5pXt1cty7/PTpqobVzMDPriuvsmuGL9SIQKarUZslS5zGgutzgY64mHCBn9VQZ26mFcHjmrWInmKVqgTG48LqClsW6xSIxb8Kep75QZ+pQU4+f/jt97cf33Z+qUHq+g5VeDxPxuBj9u6xPqCYJcbkvfeVmG5LmbtJn6whYcRkOkJ9Jtzn5Ztqu7Xdbrb0/121tw/brcOd1u813FygC+Yy9J+4kze7igvn/gX6qELHoHhUzHf5RSsm05cu//pj33POuYmdQuCqYYQ+orkRVMhEcb3qco2obSTOU4tRgm1nQQTqzlhPRpmWTdearAfQzUuuQLVZZJ6Ah1ThtGggaY8aMqLwEFMWFK5BXTRl2vWAQGwBravydsGFZfrK1bE6EWpvejkH9b22qGEcfY+DRzmvTwrFv2aLFr6/Es70SCt2vHOv04JCYFNiA/AA1a64A/OzcWEYxu4I455mE00BuhnrqW4sJhjV55JIdANcBDAS+hsQVfs36Bv3KAeOiv5oA0nKYj8cJCmwnG6fj6cltAopJySA0lh9QMyiUJhmoUEacchGyeNK8CoYc957Xbz5LJAce8r5pvYtIUKnvq7d5nkaTSTCqJapzmxY/zavTCrJZWvEx2QLp/l6LSUfTUTPTL6siCqP3zEU99ra0ydkdJUXX1FprilnD+X2PUO/UpbwezlTC2KiBjl2gK/XMNeh1lmh5GOeVpWwLfmeAPIk6SCCMJIi4ELWtO0+4ngEUB3BVO40nZy9rz5RD2/3m/tzowZ9hcn+VJEeF8ny2+YRFt9NteNI/sjgNYIPHufrjCqVEnTCEopX4YRo9uJJ1ivjJq2MuaOLLwXopEd5O2WKpKviyV7OvaSEwvasK/XkQQkM8VNQVh5B1ReJ6Bk3pb9YI3RqiLHhu9znUWAg9TOaKoO0N57Q1GrM2OEP9wka4FtjqY5xCo4UsMKFXPLZw4uGPEy4mOvZf5BipQirfvk/s4FnMxxJEEkJwDCbODaY5tMJWRnZI4ITIiLcp71KVKmV7dcZYCm9XTtBzOydMZHhHXuAY4Jedd6dvl4xl5B5UxN/H2AKk9zz2JlcERtBy/uVGyPailVYn8WABzvvarkgTIlpWO+/sgI7uxT5BDWvh8lsqfn8bG60HtobBj3awZs4fuRKLPiQI9nDfVoTJ18/9m69zijLHtCn7orXq8Zb2W69py7mFTHxzbX1apUAHa/0ujTD1X9dSltbPAfdj2f3bXYYwvCIHaa8MZshZ8pxcDxCdrLyRip4LrdkaiNvufdin+ssapokPmEwBHbrT5HM+k2Th+OHhIJARrAaoZuQ4+inm5VpGT9mPKLbi2n/Qtpe0TAe0ab8I7PB8j7u05SqaY6oXkC3jMPC45WxpW8ePpknYPAszrojzBhnyA6PYpzGWWrrDXx5dU08DVI8rMt20ju7azc7nGiYbOUs1FiYUuIgzDtcGQMOhKfHBwNJ6mpWU+LFzFYfN5L+Oc+6PAdbr8SDxy/Sk62clRotihInBqR4xQzcUaEynPbmz997lkVeYsLOVyx1rIGfxbfWAsysdmsNly8jmN/QgMn+akPDcLxaQ8OO+Qy7bdFDaoXqZOm34qpZqVnXzLCxUm0zwoIkvZT2BRa0tgRR5xOY6ZCfrlhDlPO6KvYUSQc1Fp+64ZGcjvs8NfWn+giv1MHU1NYZxYA3Yj9LA5GHOM0Sl6yQEgw/J7y6p5XPAoHHH8g0KsBv+IEleuUSuBUW0fDP1w14EfJjelQE6APg9Zl96k/Qq43hnxsNePfZMCNsVPQdnAQ3xOJCH3Bxu+Kq/plrQO+TW3gCznPuTH/HGbhDHLzK++PhhfaJmZBMI+jR6If2aU/wlD87UWl0P6idBXXsy7pBA9fLipXeEHaNYBpXlw5DWvgW80CXz+cH1t8w1SeQIlvk4/zqfbdhNAG8jOOUD3kGr/OYoU4KaFuKmIBoVwmCx+hV57j72qXHELfkflTT5MB81JR/uyfKf2dSaW8tJQn638edq06EfueMRKd50phpcDeGV8tCY6D+1L1YQuYApO3btAGJEn7PUo4dsHGxFAx1GOocd+HB3OGB5VK37+ZcjA/RzdHh9QSr0bXi15pmcF78WTqUfEx6fpPeGAnczPzWj2zf582DamguuCQXdJN/K0I35Qldeyk/ZPBNfV5CKkpfmv1w/gHImct3R5am0Fe0YT+of75pmMSK8KkXNl6AzBAc/3ARA5d9cU0wrC1T8ULQMRZTi+hweoxe/Xx6/PrJ9InNdqvVXoUlltfS1s1XmHtaydOqkh705RuNk72auPp4vAf3+yqudBhHjnC7Jlq7HzrtlRObV0rUQO723v7KCd5rzxPIXJDgvfb2igmWCSF1Hclu9/jk5GJlBFNWwiZeXUEhK0HZ56lFuaXpehzMKsjtvf2dtzurUJFjOiZ1Zot8PP14Yl6lXBpZmHFu8W8DxYm4cKYMHxTCbAhBfTEaKTWRh1tb9/f3EcUMR1wMt7CUdGi6T2+NSUJxE15fwp+jh5Eap/867fiWANoYGdCY4tS81fxXw2Z5ubSQCP2q7f6xSRHFDOxBYIZKV3jTt4BufswxlyrvMRWy7jBxVrFs9W3NjwASPijsRx4rnObbtRo1dbO1v9tayZ5cMm+2Im3W57tqp40npk3rCkj9RpBTdh1CjzVwZbWL40qXfNJoaXmcW7oa15Hfs9rS58BVhwk2wbsTlVgKq7KotPm9OkZWjyrx3vkLYQJ3Y2Y3+LBERcZuIfSQBDmtz8vY3VrtBpqQb5FsenTxpZhoahpven++Otl0JZmmEyjhn2BWV/72qUfmNtOUnJCGa8QLSfo2Q7FpyiNmWK6rKG5CvgFqhRfETIeTBeRwgcM2MEvxrf+35tQsz/hdMWvmmUzvRzvRwX6rFbXf7Lb3VsM9HU/qxEPsmCi05dfm9ADgIbo4MacadRiyVKBmE4Ci4WMooAvpv8x0ch1QNiRiIihTpn4KoI/utKIcKCKQIEaYtp2j66QZ84Q0gc9c3wrMpK8vlqZ/N4/jTAiSNCzmmGnLamp0rKUpsA9hAvUGC6JYvSWsWYpVwSAeUEHIFDTPVj/lwy0DVtLUdpvWg1vbrfbuVqu9BfE8yoZNm5bcNMJpWviDSNvKFb0a4v23rZ14lxxsb7f1D0mM9w72dzBOdvaTZLCavePSDHtwhGo0sfz5WUZzdi86p+dX0clvJ6vh3hba1s2ynWYZ1jf8rQFAhDZaDD9/mhCDCoW6BhZkBbJ5/pN6xQuQHkTrCfAsC5H5oGrH2EUmOqsHhSK2Df3PCkDq9v7O21XYC8Yy6b10c/TKGFBgkGorSk7HKWW3K3lurjEOAYsPzvgrs8sTKqB7gKW/jMakP7YCnrLaIutXDn789Bi9+gJBdYEkiTNB1TTEBXjVnYm4G+eqvrj7w17rIML2KYveGR1e+6u7hYEI5rXJuK+6nfPXkXGoIdDjAZmqIDNwpkYcRAiwxkFFNGyffqbyBzOHjJw3oSKygY7PuyjkGKFXtsFaEmORSPuUVwAMyzOF8+X4KbKd2KOYr2xZqJQZEZFhoc7L1a2LhYiFe+bV0TlsRE0EAKYE0vVyLwnCtsOHCDqg66GOlJnALCaoa5piH83d5nNu+UCzu9plY7rrvTp6DQaknGX9S3fFfAXQVCSpc/mPw4ns6h8vsvpH//jSbaBP/3C74JTFDfTpyz+gcUqOlddAR+f/eGKn+LNY146BdpU5pE9dW8ZN43Tb2euSRao3ldZKv1Byv2ImQzzWmhkNp5Lo1aclFMcpi2uUA057GaN1GexV4sAp0jNqqXxZQCwzJ2fFopEKQ3l1D/yI+iBq/b2v59Omj5vP3/pXDdQFG++idEaOcEoHXDC6CqAG4J5x1YMAwRzsPvZwcUXH4NGbyMAsbg6ViHFwbyDcwCRNoPEUgM6UFnm7td1qtt402/uotXPY3jvcOfj/Wq3D1tyNWudhuE8GfK7Y7cIcD6iQah5u2wfN1lvgtn242zrc3lstt6YnUu+WTGuHoeyUkCcdzlTYwOmWlA/2ZXdll1rAb5yJu7oOsfZhYPwgR5Ygkqb6A7H9U85xAHMJqBv+UqcyAOx0j68l+TAq1WRvu12DkMjDhDPy3JLiGWwCM4Rf9oTAY83MonsMtzkY3t/b23njFoQl5GGmMQiPeya4ONswZHWCWTJqA00J6Z8+RBXsBTnBsYnlUFX2nrZbu29XxY4kguK0Nzdi/xINbMxUDosfrlR/LKpvd2j2BApSKsLiaQ7w65qrm4xI2DGTEWYZtGtuIBrWU5gwtUvH5eDkptrw0p6qx6TxQ8cjDDgaoiz4vb33794dHL05Pnn3vnXwtnVw3N4+OuqsTDN59LPaFfFpsS9VARXUQ7AFGulXYh4HxkTLTIa98IxJMuAZA+Tmnzk6w2yIjgAw1FYKTCPUJcSH84dUjbI+RPKHPMVsuDXkW/2U97eGvB21d7ekiLcM4uiWFgz8VzTk/3G2s/Omebazt1NuewQpaM0VXhM26PLXhBOkjyc4MmYZNpUY0TDlfZx6m5eRVTzxzfD/V4QL6osWOL5eQrighMhrA336cD4aL+he/SO38Rvo7B9dzNB7gVlMZcyDeEJDe4cRRA++2W55MaGCglBWzeVfHSt4TCkUFr5Opl9AYGBGBitj82/q5Ns8i3otwQACRU9qTbPSNt5ZlikhVU8SMs/ZfNR9NyVRs3DJlCntwg1NMx5brQWOvOnCRwAseaSK3YK1V+PJm+V2E+IZ7XaztXfVfnO4vXe4+yZqtZZGUh4SHsVUTesCJz9y+recOMCZEgQviZAH9HOmqPYce3EpLXglTFzd86aFwYxLeet+9k1Zzej5ktZmkcWa1um8AB5vJyuzwoUaoQ44UEsqFcMV2HM9KnldS3dkTcbT7idYu7K5tJLVMXzUdYYsD5W76wgzvCzcruYB0FxLlkqJ/iHhvRA7rnhbcTakKkuMPkyxgn+Uddl/o42Us41D1HyzE+23d9/utBpoI8Vq4xDt7kV7rb2D9lv0PytQbXUW936RRDQd1MJM6iVGTp4NBxBt+nryARoKzLIUi7D9hRqRKYqx9qf7PAtLZo9chEKPESQrUWHqXmPCFBHSNNUfpJwLGzxp+PhH4rqa+UENeWkOzmJ8iQaKvblcLAPPC1lNdI4yaKQ4hgLmIeGO23J6UJ9LxVkzWfIFSi/mhEuF07o0xeYFDG80/Gx5Niyg47EA+Q/d8vIMcptZ7QGRx3jqoVBvGb9n0C0NaVZgIi7Q76cXoTeLkE2WsH2z7mlC0qkpM3YOMHS/hh/LAj/Ybe0uGfbXwhZkqC29GlXzJczwlGZufl4S1zlgpCbdbJmoVM2fM9InK9j32rD8k7NaLBvXTlqP7+7/XHW5xsunnfNO8LlKbq1VsNURQ7CM8Na7jDAuex0qAqyohaRA5ymZ9B96duvCPH2p2LcQ8YE/lE/0LWxH29FOtGQOZIq/qTsCEBwvzhsZY3FL2TBSaV01shtXAg8GNEZnmmV0IbjiMU8hUqqteUuBjNClC2WbR9e8K2rYLhX9hH79cHp1Yjqf/nx5cnJufux8fHdyaX68PDkutUP9dUTVkq9Nroyvh+eJsKxqy7hZw85hXh7+7vv2O0dv5DnE8Ngz29e1BKCe+B7RC2iJ3d0lIxY2L72usMtV0b7M2d+ULiW+vJyp+LOXiXSEsyU1vCDQz7G2QNqlGx99uTxDKWW3UDrIQ7ycqmZ4T25m91Rly9SDnKIt/6WtVqvV3t5Z8nbQRozU5h6A8odl4St3az45kGuYBZqfKsKMGdzHkuzvIsJinmg9nVvC77nwcDmOWMRNFQRnMjclukSB1XzyACrnkgw/Z0RM7e8axf5XMYdzxlni2/dYBCKtoOBh+Cad9PTvbvLEAD6xC9rPlNu6QWNRE8gRJOZ3RDiUWmhglqPr+bZQWqVdnvzce3d63rn8T8O5vxAqgGk+v8s6R63OL5/fXXU6nQ782/znH6vcAQYk8WvNR13GdeU6H7mScK3v9SrrA2HGddDNXmYXXh7GYDLYhlXfhOWxS+VJht0hKRumuZNjP+/3iklMf6Vl3f29ATI/+e2ic37c6/7+2gJG5QuU00BVXswGkGIwrp3StiCRJoQOE8I+1qN//HJ2dQpzwdhuOOju5Ee8w4ICKH9K2FCNzLA2gwB4zTe2HvP410+Xx2Zfn/zc+6z/VSA92ITBHvMeZkJiOi4BDaBXJBqim432xk0FEtrmvzaODq+FwteCJD2lJtd9yq7HUzyZROSBLN2PuLjvyhUqq2lhqTBLsEiK28HgZFpd47G3ZgVgdsyKmBzR2VSvlfDX6fcFuTPxBLhjXf21nq90rXz459nHFfFzS6Y1sPOB3pGmIKkpMoFSKD4AmNJyysWn91e/di5PrvNaOXdNnF9dH2VCEKbsi8/16RgPiSlVOoHm3Hr3f4JJ5fU9ZZpQvalXJJxyqdlKpPM+BzjLQQpMc3JI4WP2+qha9uul5eVVTIXcro9JPxsOl0VM8wIM2ajrMcIkb1krpLS9VsOQjDFjRPSkwnMB/z7mRUCgXhPe+WXr5PjSNpJ12L0ZNPwfZGk6RQlRpo39GKc0pjyTYb0dtEP+cnlW9iGW5NO6+cvweG48IL06dAydUkMTGQBmeF8ScUcSrbKTLLboTuBTQY/SqqyV7SVDljWWTm5c2aYiBYfQ39HGDD2aaql8As7BYKAMda9Of0PbUSsKIwblsMKhCRPgTHHGxzyTTeNP2F8LRQc4VuZfHt6mFIZI+BhT1tQyMh+F8romThJh/q33l/mJTu52gz/Qyd2+/efMmGMcB58bZ4o8mB+1L2x/Mi2WzT9cs2Tzr0yk1wyFQ/4E9ZpNHEPw2nzq3mi3plMqzVsyNX952GsdNIPEp1IQxfOx3NbJRBoZ6dXlUh3D6E6jZSLNrcYNKEbxZY4bgdF9ypDkY4JiLCEsoR3XMZ4icJUtXurphb5Ptrgw4QmzPdJpjomEUYE15EBymDm4ptEioJfmMVADyTDkzo6/MUPcmCeNkELDkCbMVoJqOlOqiMApOr242/djEhan3Ka43/zrxmCI/tcNenV6cvUeXb4/8oNuv9nZfm1oCj+YZ9w6N8A9q3joYAsc58jNw1JAdslyLkp++T1UO4Sz7zyeS9tXNPvJczxa361KaDco6IwMG3Ae/Oer8uiuwackCtEBospg/MqG3syMK0TuiJjqKQyS8Mz3ZwZ3006IoDxB40yaLsV9h/ZFEuNyEZezlpsE8OE+QRsTNtzIk74BODrSv/t7AFnrnTcQGEDj69p4FwbwOVBgFgsGjtt/3ATqTPHJxswi3/zHjandUmiCRY52aIletucACCBL0zmYn4mHrB4c4nRg4I2/XJ6ZTgwGVQYzpXXplGdC34C51p0GGwfgu/MIAWXoxrF2A0hlALOjCr12BYk5k0pkYEtCemDYFgJge3I2TBz/0ShmUR8e7u7ubBnQnP/7xz/s782//0PxyfJr5tTTS1i3zS/MP2x4tQnbXCJJ4D0kl6eXY4V6oQwxou65uEVjzqjigrKh0VreKnb3eJ9o9Wi3i4XexDLcABg8BpTyoc3v0F/VGnigCDPg5qEZap4psBoVDmC4X8bEbkX/NT8slq6nqyO0Aeg3KTGJp4yrsvZaaOvo0R758/K7aoKlDBTcylGv7fBOidmrdcn8YkP4XLg3T4V0L2wgJiAs0MxW5BuroPXZj21fb+6j75hHid/dLRfzLP2epjn5IyO1Va2AvQYT2APo87CASfMXG5WuYtyfYb16MweldMf+X7hjjVEXNiUIZ4n0/YSL5jrj+rugXUQefjCl1gHtkbX1hamjg/n6mfKfagSTGWaNWehHNG0oGCLjicrpAdLNJ2/st2fQ6BI6gIc7BclVfaLuSdCFWk+q7rlxkVZhSBgvlAiS9Op1Ca8g+DscEdDhblK4c8zEDRDSZEK8rpFZ3/xp5tmtYBsHY5kPQ6h5Y8B5+Dy5AYBe4S9mrwxjY9vFSIgiYgx5jhNBYipJOnWNRVIqFUrpbaFOV2aDAX3wI8JnXunL4nBry3zEfCLiYvg6Qldi6l5jJxPBH+jYFHtTCS2s6HiSTpHCt8UMFWt+6/VPcZ+k0rzeaDsTLuB7kqbA/dXZscz1YMyj7LYCx2xliBB6H8l4ROrLPO3C6I+reriWZ/0f88J/c1hpjBt6H7ngVyAOt3XrPE5+EtegxiTimoDrHxlOjX1nPwOun3Uyg8TYNHUiMQU25CEmE2MljbhtL2k6qM0cN6svIojbYBAuLTR+maUAinaomcsoT/i77c/ss4XBVdJGIswcY8Z4buAWzmYjkEAejpllqE9Sfl+tKqr1SlH3hLI1sSssVTSe2hHM4TLaBUvljQ0fK7KjFHxu4FXaci2v/dxmlll/W2+gdkGBNQqKICfPXD7Wq3LwZPkYGyYypu8tJTBN8+BDhULAcsnKR731FZ/0gMFvcKGQwcCmJGkz22whK5dX5Ors+HXDBM18InK+IrmTCIq54boJgYoNNUVwfCpCM7Pz5jG4/JN6/WCHfN/3Dtw5j105+UrMd/nA75ffbA4svqZN9sUOv1rvZ42W+NLQEtdAiXOK5ofASFzDI9YAj/ijIyOuQRHXeIhflcrfCiXh74SC+LcBQPwbYR+uYQ+fJ5814mFZJt8v2OEa5/Bl4ByuIQ5fBsTh3xjd8AcENlxjGta5R16Mf79COMO/G5Lhjw9i+PfFL/wxoAshjZEkEVZ8TOO67SHz+mfmCgpfjIkJqY6WHo8lRdgdFZyNw4xTwhIo1YYEQpsXCTmUJZH0cdL0b8gLhaCcfODD30Y85rHZXmclWVVJKZCMl9YzpARInNDfX47w9t7+MnKqrS/bjJB6NClBSmg/NLO8a8p8U+9qrgcHO5iQvebbfdxu7uL9drPfIvvNVpzEO+2dpNXuL9S11UtC+8nfShh6rmXlQVPSJ1g130atqNXcbm23o9ZetL3TbLVarfZCcQ4nixrr6GZEoWxVHcxsDkuMTSDEZ1orKPAxdAa58b5gfkjvIDnbinFWUP4PPZMDLrL5WxoOBB4TfRRrkkZY42qLI/2UeS/eTJjmulgR7YP+aXB64hRLSQfFWhSFY0Vjg+ND4pEJM/iHegv0ZGaKtJVop7Jj0bgI5WMzMHwv1L6rWQWsB6hPlA1E9H1gcCEUomxIpIKyULjQBVGCO5CcsHAGD4eGPVjkcmTh4+nV5QnqXF39n6N/FtZkKHg2iXBKcV3pARtXWpPrCV4R6T0VmBcCBBgKn/gAQfU71JwpkcGd70pbw4JH2NXY9DSOb40YceGh2xYW+LaV+m/a+ptG1+zXEdQocRUOKcgfGYX+yVOewTJlkiBcEBq0oDVEe16iUvnk5r/Qxkc8JDEWCv0Mn97fQPPjRZjVqO0agaXI745nrQEIPpTa8muQCz4cd641oElZ+D+3Wj5OO6eka/TUN2bBn77jHQ+ZaSV5vz89n9taMuKuG5EKZC4KsFTPEH5hc4e7fnHh50NWbPr5ZF9gp7wILu6JlcLxbTSmShDtbG/Bt+UWHIqteZcpd/CwjOZ26x57e7BxeRuQxymAYJprCqx7X51vbz9TvJD/2gvP/NkjxXW656+1P/9HRtKgK7FEBMcjb+5zsy6mOzkpm3ztvfb+wUKCCSMLK1Yhq6/D+xQQW40y+jPnw5Sgs7O5kWFzacScDfQC1HekcxP3uqdG5LpnEECajGRKALawo+C6Z/rDX/fgFcF8PDjT55yRrTN+v/WRJDQbb32gw9F1T8Y4JchhTlOGOpMJYQl9QB2nPCzoRDu3JgvwE78Ygtz7YUARgsGlL01MElNSGGdS8bHxdWV0zU4eJgBdEo5awMdE6CeAjO6aOUjifsUsMMQZvzc/GN7Mz5rBksIwH3j+SgerUtNSHxdquZwvgwH70eGe5C961uyeZe/0Aj1E8P+KuCkJSekdEc4L7LBhSgQ6+efcEcBcEpA2Gtm00fodu0chdgvpq0X8TL+P+OAp/MzJiMrR/1sgT2mmkYkpqiXzmK2PJa1snmHr6ORQAnoB3dCVpcH6OsVpCp+2DhS6JWRiLmuze6DcV487fy3bLHdKCdrPasSH7ABQHh8YtvP5AqY7/pc2zJujmfenaJJiNeBiHKEPRJDNTb1rGGdN8jDCmYRM7NSGjY1eCdxca98Qq4OMPeMqnA8RFrEB2or5eAKJ0kkjx8xpIMLgNZUk+eM5AeAs0kAjmiSENZAgODH/ra+qhr3PGwBBVVEhtfmvDffZjQbaMJ9+BurezPrFPCE9//QcJVT71LU/g5tyRCwh8IRLOUiaHpOQYdB+Hi/aCN4W8wd0aVA3LBYIlfAXkuQFQIAk5Ye0OlNqexU+KSCN3tZ9+IJQZGQTvM6X1uZ5QdKnV6JQz/oY2Fmf85RgViXid+ZPAN1vIEIQHWgD36cZUOngG8rJ/UpkZEVbSv9E2bBXm+O+aRx3n1gx7y6i0n/UfttsBDyZpK4sboxZNsCxQVgB78ZhTlmwtSgYk4RAGSm5s9gHnYnecz996gKeS1UtzjjSc5LoYRJHE8EfpiuSvMIqq08vPw1kPPPeDqRUr8AgMzVMKR8OIYkYElCGAk9GNEZECC5kHoINR4XUzLCtCRdI+6vKzYfOCL4jKGM5+Cn1MH/w1fwr5SwBP6y+azMWj4h2cssLeHJ5+emy9+X86vJL9+rkuHf56dPVilbQPJ/W1Uyia7MgWKEZU+LUYMk6dhCR6IiLCRdhBHdJRhXB45o1hJ5ilWoCxuPC6gFT++uVw0RwbZFHuVbwgz5TO5x8/vDb728/vu38siJJ67tP4fE8DQ8es0ePywD+ha1j7hd9alw2cWIAr+EersTobzdb+v+u2tuH7dbhzjPw+b/Crj7bcxnfT9ylm13FhXO9Av1SlVkUj4qVzb9oRYOV860e0zXme84ZBiAc+H1iqvEKKOWFmmOo9CvAO2t7hvPUwoBi+xyCQH0ZS8cox7JpucJbH/TrklKvNmGgKJgOqcJp0ZjRHizUu+MhpizAn9Pf6FOm3QEL6hysT+UNgQtL8xX1v5zYtPe6nHMIeLwwjr5/wZub1x8EDDCzFQvfX5gb/e0VO7q5x6e17ZgobPqQjTAbPuL6mr95CH8YJnbw89o1zCbQg+RmrKfySP76zBGJboCLHM7RYrQjnPwbdIlrsAYOg3l9lJBiZIeDjGiW0+1RFbSEFpVsQu5obXHEYxjcIooZNWd7sISkl7yd+dsAzjLjPOS6+HHjG5CzfBNQiWycPUKnPk3donIYzSLCCJFpwtmw/mTeda0ki60RH5MtnOZr9GyZ6Il7ZsJlxVJ5tI6h1MO2FX1CLkUEN7henL2S29nMNd+YwYUynnme/u8z/M01pnVQKG2oBShr1AVi7SBDkg4iCMkoAi5bTdvrI45HlBEUTuVOysnZ++rT8vB2v7k/N552BWP9KWRQ1teQ591UO2q2hYXm51FezqhSKUEnLKF4UQdAsxRPsl6NCUBHF198pPzJtTlliszdF7iKD3t59oJ7bZHr7+RBQfVLYhTOhEtJ+ynJ0dX0jJvSX4IROjXE2JBX7mMYZMV+RlPI8tP2JE2t1ov15WSxjAfYPtuOcQqOC7DC8/KbRcRBHiZczAVsP0ixUoT531bm8prhSIJISiBnzcR4wSw2fWMWJ3VEcEJEhPu0ZxN2a9qLQaau24qdIM70zpin8B47wDFBrzrvTl+vgDNIt6qJpw8whcnoeuyMLUG63uF1GQjQNQhw8wO67bzLU06YEtOwa/HKUCutyPMJapA7NzGnes/D5kbrob0BcT8PgOt4eAay4hNcyB7u05qo//rRdetyRln2gD51V7AuNd6Udls9dVkuQfg316zLH2SDo72yK8wMV88VJs0D9jy0MhLEwmai+a7BmQWNgoc5howuMBBjOB4hO1l5kxS8gFsydU1o8hZ3BaRwSezQBrbcZZj0p0hm/abJ/fBDAvwhI1iN0E3IcfTTzVKawo8Tj+j2Ypq6kAZWND5HtCn/yGwwuO/6/iVUmrBAIEVLxyo2AVw9fDKPY/0sbrojzBhnyA6PYpzGWWoUoLdOV8nHIMVztQ1aRGPoXdu1GxlOKEy2ErJrzJktUR3mqy1FtOvK3+ODgSR1lR6W6DezrZaD5wNCuL0f9jh9mm43GUBHrIT8Gm/2EvV6qJUQfUeFynDamz/X61mWbolwO5/L6VopD4tvmwUYWH7bQB+Tb3Xhw2R/9YVvOF7+wrfjPMNmWvTQWUE6+fkttwrya9YXM6QvrTEAEqFnEElo/UirMB3y0wWQT1QG/C3DkiLpYITlPA00FmHFDY/kdNzn0NlqBEdyaaes7pZh7wvdt+br+vVDNMuaEfSAi9s6oU42O3o/3MJTY56HBQ+jWEoe07zRMw5efP3W94L6xEyIooEwEsS++rmhfYoMPBPPTlQa3Q9qZ0Ed+4Kb3uOpNP3ZlN4Edl1gGteZ2PZZB7B381iUz+cH1t8wFQOQHlnk4/zqfdd2v4YXWJzyIc+k7VzYscDLxAT/ukoQPEavOsfd1y7Fgrhl9qMCUdJ81NRHuecyaIYU4zQlCfrfx52rToR+54xEAcATlTkUcyaDcuL+1LeuV9ymY7tu0yjh9yzluNBUxZfpoA5DneMuPNJOJ9oIDfa8e6vlYnyIbo4OrydYja4Vv9Y0g7Pgz8+h5GPS85v0xkjgZua3fmT7JhyAMdgj5ZIm0E3+rQjdlCe8mW1IHnxTn5eQitKXZj+cfwDyq/LdkTdCNh/UP980zAN++OwIGw8ILDfUDxZx/ja/M6d/WFsm24WgYyymtvzt9Bi9+vn0+PWTz/Sb7VarvajVBPN8E17CHMRKPpZ5XAcIi3GyVxMnH4/34I5e9Fp2CBvtmujrfui0V0Jgnt1eA4nbe/srIXKvPU8wb0Ei99rbKyBSJoTUday63eOTk4uliKQsx4RbefGWHjvvB+hMQ3Ov5tafLXotKbPtvf2dtzuLqrMxHZM6Mw4+nn48Ma8oLrUozBg2MYNQySEunHnBB4UQFDJoj4WOhxQzDOXLWEo6BCwfuTUmCcVNeEUIf44eRmqc/uu0c94JDIQBjSlOzZvDf9kWkD7NIEK/avt7bFICMQMbDZjR5pR58erbxit+zDGXyqPDFli3TdUW3YPj+rbgR70Dw1WgDPFYQediuy1xGMjOd19rf7e18N5bMjeyIjXS5zRqJ8n2E11U3jU6K+czV7u1xTzoUO4uOoxYk+Nrk/hKy+Bcv8XdM37PakujAhcYJtgED0pU1pUvY83M2brzL6uqf+/s8DABtzGz6t7Fr8jELLjxSZC3+LxMzK3lN8qEfIuEwqOLL8VkQoXFkCjvG1cnFC6cTTiBcuYJZnXl3xp/FfAHYJqScd/IgZ6wctlpTZO6PsPmKouOJuQbVOp75oPfLsj7Bc5TiBbgVf9vzWk8ntm7YhbGMxndj3aig/1WK2q/2W3Pja1X5piOJzWGZTc7JhLr0PRMjgg0zkYXJ+aUog5DlgrUbELLRfgYCuhC+i8zfWcHlA2JmAjKlKlVAciWO63soPM9oIBPqH1y5wJxA9TGE9IEPnOdKTCTvh5TohG+I4jHcSYAV8c0vrg3/QqhTsJafAL78B5Qb2rhi5UywpqHWBUM0wEVhExBq2z1Uz7cMqAMTW1Lab22td1q72612lsQ66Js2LTppk0jnKYtBY+0zVqOybTi/betnXiXHGxvt/UPSYz3DvZ3ME529pNksPh+calnPTgqNZpA/pwsowm7F53T86vo5LeTxTm2hYl1s2mnWYbdDa/5AfDJRkzh508TYtBsUNfAHywojyXbR5jXDmggQZnx3goR6aBywtgtJiqpB4UioQ39z4rmjO39nbeL3u3Gcui9dBPxyhg4YCRqK0dOxylltws/j9bo08Mig2P7yuzghArAm7Q0l5Fj9McW5COrLXJ8NYLLRkDQ+AsEjUWOyxbURb/qzkSUjTOz2rjyugcnYn9VD86qpfi7N998UibfWdfNJ3h5Ca04vrN2m09I88X04Vioz+YTjP3V/Tdqb7A5J+8voBfHN+ms+YQ4ftDGHVUc/3C9NB9j8sdpolnF4Y/WPfMrPP5922Z+RTB/r36ZXxHG99Aos4qFdYfMb9ghs3IB1q0xv11rzMoF+MF7Yj7N8/fVDPMpXl6C6/39dMF8SpIvxu1eqP3lU5z91X73SvtezsvoC3Cyn9vw8inW/kYO83fZ4jJkREjVk4TMc9YedYVN6cosHCplSrtJQ9PowlbVgFPsW6NJOhyp0GoxlSuevFkONyEe0G43W3tX7TeH23uHu2+iVmshpNQh4VFM1bQuYOEjpzfLj9icKUHwAmhbQDNnimqPrBeX0kNXQvjVPW9aiLy4lKfsZ9+U1cydL2DpFdmqaT3OCwDPdrIy+VyoEeqAk7KAYjCcgC3Vo5LXtURH1lw77X6CNSqbLQuvgqG9rjNh6a7cOUeY4UXgNDXdgNxYshhKNA8J74WYVMXbhLMhVVli9FiKFfyjrIP+G22knG0couabnWi/vft2p9VAGylWG4dody/aa+0dtN+i/1lQJdVZMPlFEtF0ZeczqXmmWa6tPFS2VPWOpPpvQ4FZlmIRwsyrEZmiGGt/tM+zsAzxyHn1qtjgjgpTSxgTpl33hnlcTzkXNuDQ8DGDxHX68YO6jsceeMLY6w0Ue/O0WE6bFweayBVl0DhsDEWhQ8Idt+XUkz6XirNmssBLil7ACZcKp3Wd/M0LGN5o5tkyV1g0x1cBfhs6ReUZwzar1oOcjvHUwyHeMn7PoIMQ0qzARFyg308vQs8QIftYb3vM3NOEpFNTrumcScXdj2UhH+y2dhcIcWsBCzLUFleN6vUSZnhKuzY/L4DPGhBfk361hFeq188Z6ZMF97Q26v7krBZrY2QApJEe393PuSqSWTzSm/G0c94JPlfJob21tzpiCNYK3nqXEcZlr0NFgGszN+d0nvI0/6Fnt+fK02GKvbkQH/hD9kRvrna0He1EC+TIpfibmvwAQfAiLP4xFreUDSOV1lV3uHEl8GBAY3Sm2UQXgise8xQihNp6thTI6JpduriteRnMW/mFPf7QT+jXD6dXJ6Zd38+XJyfn5sfOx3cnl+bHy5PjUg8/+NICArL1Uz08TyhiVXvDzRq20PEy8BfVt9kiepfOwfpjb0RfP/YA7+AblS5w7Hd3F3DzbcJxXfGJ2U7GfuJN6XKdy8uWij97mUhHOFtANdfdKPiy0CM4pewWarZ4CABS1fHpyY3q3llsXW+QpLLlv7TVarXa2zsLqHVtWUhtawEqdlhHu3I/4pNDq4VZoEufIszYoH0syf4uIizmiVa2uRn6nguP+eGIRdyksXMm87u+SxSYrCcPoEIuyfBzRsTU/q5RbAQTczhDnCW+14WFUdEKB14vb9JJT//uJn+l5hO7iP1MuS0adMMz0Q9BYn5HhIOthO49ObSX75WiVdTlyc+9d6fnncv/NJx7pV6BrvH5XdY5anV++fzuqtPpdODf5j//WHbVDRLb1zrmuRTbyrU9cvW0WmfrldUb34zrcFq9nC68DIxFY8DUqr4JS2KXx5MMO0JSNkxzr8J+3u8Pk4n8Ssu3+3sD5Hzy20Xn/LjX/f21RbrJFyWngaq80gjwj2BcO6XF95cmdgwTwt7Vo3/8cnZ1CnPB2G44aH/iR7zDggJydkrYUI3MsPZpG3jNN7Me8/jXT5fHZi+f/Nz7rP9VID3YeMG+8i5dQmI6LlVmo1ckGqKbjfbGTQVs0+a/No4Or4XC14IkPaUm133KrsdTPJlE5IEs1CyzuNfK5Qar6cemMEuwSIpbwIDxWZ3igYJmmTa7ZAnGRnQ2j2glPHX6fUHujKMO96QratXzla6JD/88+7gED7dkWgMLH+gdaUJHfG2qQM0KHwDmYfnN/9P7q187lyfXefGSU/vnV9dHmRCEKfukcX06xkNi6ktOoCus3tmfYFJ5fU+ZJlRv2CUEUq4DWolE3udIS3lVt+mEC3lgzF4BVct7vbSMvMqokNX1Melnw+Ei0E1eaCHpdUXhTWaQtR5K22hxJmSMGSOiJxWeCyH0MWseotWa2M4vWyfHl7bLoQP5zKBz9CBL0ylKiDK9kcc4pTHlmQwLoKAn55fLs7ItvwBv1n9ehq9z433oVaBjaOkXmq3Ftui2rbpBLAB/BprpVaVKbC8Qz6uxZm3jyiL5Fxwwf4ca0/BoqiXxCbiFC50y182/Ff3/7H3pcuM40uD/eQqEO2LLnpVoSb5ro3fCZbu+9o7r2LJrenb7m7AhEpIwpggWAdql/rWvsa+3T7KBTAAED9mUbfmqqujosCQSyEwkEpmJPHxbvG6um677NFciEVORyy7q9ebrTPERDRV+cnU8auZ9JKaUJ11NF3wU8p26NIoy/Kz5CP/i6dWm9wNPr7bNx8qYUxp6z01zxb7jn9r2NH9hn0/8YDt24qc8i/8zIf6Qf4WkuS4NwZuLT12jtOpagdG9ZDP85ftWb6/rRdjUnBMOj8XZJc/iACm2LNPmEEa3EirP4kKTW4HMApdrtuIpwscJkWLKSEglmP7aaJzSGQEz1RRfPP6sz4R1kaELAFkinhUFXygpoUZsZRDTbh07iEEpxMJxiDnsY2F16wsc4gL9+j6EiJAGzKTjaThjrlhGY3L8+WrbjcmSMBYm1vnijwssSPivC7J6fHT2nnx5f+AGHexsDNYQJv/BIjzTqub2bsHVHjVVriy4hbsHwK5ps2XK341vll73tWh+7Sjs0kfd5EVBS9fyJdPmiNeqE5iuTdHYs/rotludZIrwEeEKi4TKjmbgRCjCrlg201NgKdLK+5XB7bQpy7iIyDSX2EJzaMsXsQhNH2aDo4pjHR4eMrKSJuOVIioYqs0G+rvXW/1Wc9soo1A5elnM9hmrxHqCyhTJgG31y4UntpRIVyoLe/HLBSbiKJLSrCjHZoC+S4FxQDqP4xYIV/wPD59ZfzzCOqhfv5xgqXUssWG6Tc9EDp2vC4k68xgE6vwWFjlPyIVF7QJKL0HNEVVqEJmxUCRSZTnogBCH5td9hxomBRro+57rHSzLurebmxvrWEHkb99+Nd/j51+USO+2Tlb0PIe1evM1cRcATiQCO0siGdwbFDR0tGsQHTwhCVPXIrskU5FwJTKejFEiOW3WnstDpkWfYRFTA5BKf9EpaPckFmMTqKBf1dJ1pFiClY99VRJd+1RNqp3THY9MmWE/95oblkrbrNAC2sHu1wyjGhOh6pLpTuyiR5vz8904KaVSesLrwcvjmuGtgDJH5R2CVBHYVgVBbnKPfjaODw8YT9Ia0q7cFb6FL59u78Chz4m5AG9u1jM27nS/pKH/lrOlpSmAbgUTmA3lAoQAMfzFeHKbkHV7Uq9ShfFrZ+Pf4GxEBcyvQO7PEugzhpbV6UTod0FaZIXpj/muHuyB0cWxYTuF+Ya5ck91vMkQWVTh3IhYcz4hbJqqAh4AHZ+8MG9XymtFfASXWgoigIZMXTOvXSo05r8WaMLcVQFAa5BlLDpfrpl2Bs7T8YSBHLaTwrmBE3eAMGnKnOyQ+RB/qlxJlXRXbyx8GFy1KyMh/Ou6Fahc5H9RFfuoA5sFiJhi2RSC7tKMhVyyeGY7B8RcKhLzy1JCpcxHI/7djQjPrGqB/3Z9HR/BJwKRjdcCcpbN7O1kmmbiO59i9i2X0FuGT9N4RhS9LIddGPVYr3lMhyyWeMuhdUI4RK9ZHAP2ZyeHspBxoQjyy4aCTfdKude8I8MJW17o4ymMPl90w3FatUnwZvvibaOyjPDOOZjvSALLosvcNm4S22kCoz/RkfktpzHqYuYZMMGMsedFY8axJQNmWrDvIUtRo5kI05cNWxhVtpWRCwH4TCgQlJc6OFQhgOwNjnOhYITfTeNRF6IK5otW6GDmkCaJKJTR0h7seBQoXCFVhIYsFtfNIqFZfpRljE9b9BtRqYLpzIyAmwilCJXKKQzOT2NGKdm+gKs0uTpOylkGlvlwoBmoXxJUndKGL8DDg8VYPbY+UzHGCnql9JmkMsrjwgnQsPGpvENKm2Z3JdJzQOoRDgs2GpkwG60GI9sYWqyys5PDtQ46qVz0a7EKheEGQrdjW4GA+PQlgrdlGtwi1XkLn1fxpF4z4IqXfabAeTLvOClWot3BAt/fjcFs5eklMdZXM/z9rZOfpeCeQym4n1XgbiDHiy0A97P22wPVfnuNZd9+0IpvP4u9NVHi1aetv/YSb6+6utsrL+z2s6bb7TT5Ucu5vexKbj+LuD1dEbef9duern7bD1a67ZVUbftZsO2heeHZ2Mr3rNX2I5Rpe50V2n6s4mwvty6bDcQPaMzpstz/K1r9hQlWmXQS1k5tWvxLBmsHCV8Qrq2yHFC12R9+fgCE31HsnxZeorJJS35tE8PnWu3o3zRzz4L/TH6fQKivUP6QGfuWc+jVNhM53HnlkhFKPhyffTki+2dn/+Xg79AGyyuB41Dw0A1q2Qdv/iAr/+zuj1miVkj7LEi3NEtrTgTrwqPaghQmKtw7Qg4OVNaBxBwyZBN6xUXmU89dt0xFxGJmVMsa8XziN1PcH7SB+A5GHtUJfdrb2hosTN4l6hgr1TIFL4rEcKtcI/J+9J4n0cJUTmOqtLBaqoxxkzwuvf1MrX/4mVr7v5/WUqX2/8xt3hP8SfYPTa2Vg8/4xwlPcpM+NaXhp1P88yNGGsMHf8hPoxEPGdnY3sLnTik1b9jefcmtHGHZwB+3iSMcfZuFnJnwTkJu2eU1gD+yUo2NxXjEp41ll/vvyRLDzT9zHIwlDOqrYO1yqhQNL4MpVxmD3vV2gHWQkesLL89SsyYn5t5eq24Lbli3Aj4hF9qw6CjEHfMB+6PihzMh4tLuTUjLbdS4chrD+oLpSdouhtKaUPg46gBM1bQIAflfNyJc0tJglE4p3Iissu/BfD7FV+T62X6v1xusk7U6xeCXJsIs8yD3k8gtr7Ymkk+TGoPcn0h1GpVz9itkemRJm2fxcyKWP3ydcG1HKdOVhRPwgz/O1rSz3Xt32oEWI6d9S66f9Xtbew3cB9/PodDD7tEHyQ27QfLeqM4vvA5ztKulrcOBmE5pEsFlyClikYyxWXSaMXsdX1+jJxIQrel5i/2yNHq2f3cOYWU+fCxZAYHpKDD8We8rf/2x7kfeXq8/T3QEvV7rm+s5xH2GYma+JFlwgW421Za8QJ/FNctOJyxur7U2r9DTCJnWpPbJO0+zXzKpF3v/5uVwixGj/0VxBdvtBK/rxpnI07cEtepKG3bN9M4rqwSh+i1thyVYLxTyAKWpQyHJSIS5JAK9r3Z8QlJbl5YryeIRnEkcSqrBvUM8I/RK8EgSnnQjlkK6IY1nkssi1B1B+B5s9fbMqP4l3YjHNkDbVN7XSP2lgSgqM3Wm/B1tKRTydLI07/0p5ouaiwNbagOnRHaM8sx9jSW5fFLXxOXJ6fnRweFvR+dfTvfPfz8+++18/+j0vD/YPT94d3COV+ltN2oYc5aooB5v/+Ap1kcfurZkpVQ0ibo0Fkn5ylVA4mgRRIKw1WKhcpkD80xzBX90IYdWYm1bclFH6TycQLEaCddCRaCJGxRScjCpFe8QqILMlXpLlePjIGh9MzYPkiWReB9qSIpRidbe5Kai2JReMpKn1QtvRwwA8aa1uNMaFLV37CpQZcJ9itAerMgCEY9+GCTKFYCrnozxxwouykqH2L/aeyINnBMqJ8E02lrSwhyUJFYy1qo4h9g4u+0/HG6RiI8ZXmUeHn1x62cuGB31xKjNlqkEWmHGloCSIhpX4//ys/Zc8FVToBWWXXWxVTBGbSV673e2D3beDw62tt69P9w53D3afbf7fvPd+3fvewd7R60bGfhrIie0/2SLcvrbfv/Fr8re0cbexuHeRn9jd3d393CwuzvY3j4YHO71twb9zcP+Yf/g4OjdoHXcVWV1iqPmSdZnsLXdvEKOhlfF3fn9V6gYFVfqYfbN9u7O++3t7f3e1ubR+/7Ofm/3aPB+0N8eHO2/2zx4d9A7HGxvHfUPd3Z3tt4d7Wy+e79xsNMfHOzvDQ7337cO8TY4YhLCkhatIb7KywC0ZdsBAvsJVLvGg6hUQdFbpZrLo0hJ+iKEIgf7kLp0nIwyitWS8oyRM0anHXJ48KvLlj08+HWBXA4z+b/pxrKObxQCWGSoKPCP80ooeB5pHXuCCeMzkrJMs5pmsdPTk/VC7yZkQpNITuhlvfxTtMm2hv3daHu4tRXu9Ac7g929jcGgH+5tD+mgfa8cQ46HyPI4pIqtQyaEpyNDhTacpE3Sh78zG/Ij3gx6g363p/87g7yIt73eYr0bPHzvnfWxKMLVJJDbkO3v7fQeAlkoEpUtMx5zXyveIY1jLSwTcvrx2MhUxeJYmmAeyCTEDJmJkAqkihL4jXdWWvkA4eNKsSm6PvH+UBtTRImA/I6V/0qx5leUx3SoRYILNHfjjpmmfMrRDr6ImBZw2PnKFJVsThZbuIqkpTnKyqeUzzWJXEhiR5ZbJfJ0hr+BKD4UYT51BeUfSBLLPMVmP+doSy8ryMSZVWaaZt2hZMTjNxMWx6LJYJljwQ+2ts//4+CDtuA3dje1PVM8eHRweNOjbl1W7mT//KwL8HR1Afwl+NGLAjTS4oVVBGjA4TmkN7ywcgANVHw2+Q13qgXQgNBT5zYsvRDALTg/g1yHR6kC0ECGV5oc4WP66vL/q8i9nuR/H7PXlvk/B7cfN+1/DkF+rJz/OUR4CQn/Pug/s/0fMdu/RPifqf6Pl+pfIvwrz/NvxvVlJfk34fAcTOCXk+HfRMFnY/7eKb2/CaOntn8fNLf/NgSfgbG7aGJ/E0o/gOH6IlP6l2nPzAlgLCwc22Z2zK9YYq5JOnihSdM05iEdxvWbaMnCdLC1nbW2XJhUdBiDYG+B6VCImNGkCaF3+BMZxbSElin/fnZyShI2ForjfdU1lV4bTq14OpVKZTSR0KjdxMkmhCWgD+nPeZKwuPV2S9h3dW5DZh91KV2c7pDBVwA3iwLy2dTVRxuL8HIbj+P9j/tF++RVv1MQpwmFsGUqtZY6ZYmS6yqWXddYTePQxXHn/hB8n6hp/AuN06RrYezySK5VQqRMR5bCaIjFNcugxUhj+6v1ftCa6TIm8+lSGY7LSnA1MJyZF9rCOGw1e31HBafKpa3ZDO/Tn2fEr4Ft0YjfOkpPFfE7D5IlkXiZEb/+WtxpDZ5nxK+B89VE/NpleskRv/6avI6I36dclYeO+K2sziuJ+G25QsWoLzDi1+C41Ijf04Vie2sxvcUZgbDWTLlHie01k/+bbiwtiKw5uBcnfrDg3o29zc3NPh1ub+1sbbLBoLcz7LP+cHNrZ7ixvdlvX8AJ6fFQV7hS0Wlai3U1gZ3PIbjXw/dBbnUXQfjRg3sNsssNND1tHVJaEcgNAqAWdLQ0AfAzDvLp4iD9JfjR4yAbafHC4iAbcHgOl0AvLA6ygYrP5iLoTnGQDQg99T3Q0uMgb8H5GVwNPUocZAMZXul1ko/pq4uDrCL3euIgfcxeWxzkHNx+3DjIOQT5seIg5xDhJcRB+qD/jIN8xDjIEuF/xkE+XhxkifCvPA6yGdeXFQfZhMNzMIFfThxkEwWfjfl7pzjIJoye2v590DjI2xB8BsbuonGQTSj9AIbri4yDLF/TPzS0H1E1IynN3NWGvW5OaSZNvBZ8LzI+5pr5MDqt4SInGLR2jtu1WHJ44EdN/Zj/ySIMoYMrbBcdCIeIj+ZtKNrCo3MRdGyX0sTWRm7CqY7RHHxK2LwxKjsvVEfb/SOlCejRtmFUKLC6vxYTKqMhC/5iIN/HhzNmLqzgfl+k2jyHUD0chGIkKIX4vQ6ReTiBUABoGcGkwthQCCsw4+qdxkMGO5eSiCo61MT+lrNsFiBfFNw/Gu3R3b3d/nAnDKMt6td2BWAfkXRV6sBnLLsqsWZyGjPCroBUMb9kPmVMPNqQacuRKDFmmiJoIdmbOzMy1dZz5ug3oUkUo6XlJuGJYlnXxE2yyJJUVsm3ORztDUYbWzs7w43NiG7TjZDtDfaiHuuxzZ2N7b80cKgpF+uR2eLwyMS207ZmV/8djiWUJnw80UQEkPV71yK7JFNGZZ4ZgxJ42PGk4V+3FD4X2zOiQuReb9Tb3qG0N6R7vcFwpwVR8wzlmKlL/PXLCXycX5f465cTW3EYjsFI665QBAhtQqFBMcckzZS2079+OZF4a2metEhpugwzRi95MiaRuE40Owkiwwmbsg7B2k4dklI1Me8LYqNs71NqGAdekvx+cwijW/bJs7iQRSvlslQrjmUIOU6IFFMGAdNaaGk6T+kMK2mbsPbjz5oK65q0mt4Rz1io4lnHuSNoGTU0swM9Nvg49NgdDBt3d87kGrwbY6Hn0D9dmJJaSDkfQkRIA2aurjWcMVcsozE5/ny17cZkSRgL42+8+OMC1u7iXxdk9fjo7D358v7ADTrY2RisIUz+g4XrxLpfIFh4qOmTKtgxZh9acN2ICPab6jnYUBDM5TTYsPdlcQT0BdBgFYTDmFstpe3kDVqL2fIONeAlCPmNbDRezGiEu0d5S3VWH51LAlEHkinCtdQykdcdzZeJUPq4yGZQrn0Cp2b5/crgdtqUZVxEZJpLBYMM9Ymg4WNR+UQpUhjw4SEjK2ky9qpm6ddXAv2dN9dHoUzQ8jXWjDN4gRqk4SxOOwupJKvWylU0C8Z/rnUAczcmkI1qlT7x4wcdY62ujP9c6SA8OMLKWp2fUuPMskw0yuh42s5nfSce+iwyZZR0I1YI3GjhJvjlwhMySqQrlfW6+OUCr6hUSW+2QBv0HC553Ea7tTEp5stH7glzPMJeG/p0gY6kfKqlIk3giJyJHAq7FzJv5q21VMKP8uIJucizONDjXUDSFMSegszEfcsleDITjHZiEVqBoIxaQQTqlhtSijwLmzNfbH5OIY3ebm5urEtGs3Dyt2+/mu/x8y9KpKW1scLh2a/Pm6/JVERalYoKiQZsK4lkLCnRzdGrYefzhCTYgpFMRcKV0HYOChQxBEUocqflkGnJZdgCVjJjVPoLTSGHjMRiLDvuPINmB4ol5N9aNjk7w8QSgwJS2lA+X0yZYTn3mhuWSi1nr6l0gHZKClIiVF2w3IlF9Ghzfi5xT0ql9GTPg6cbmeGL1hFwgAUVGNRkce6tzKMmlTk8+WcIsVKZVmQLXiiiH+Stsawb4RCFLK3BsblZv3DY3NwoAQWm5jLVDpjAMCv+OmSofeAvJm2vCQfH75qmFaaqnS9/g/MFdRPfA+PPEmiZTcsKZCL0u7ATs+LmDKMpPNgDo31meEUH8w1z5Z7qeJMhsqjduBEhpYAmhE1TVcADoOOTF+btkCZairhrYw4pC4niVDEyZOqasXIGproWqLRXDlFMymQZi86Xa2+cedZlMSmIWmtBaXzTlBUNp/Mh/uQtY01b88bCh8HAWxkJ4QceregFWfG/qEpK1PoMXSOmWDblCYv0+RlyyWKT70Eh98+4K4oLa5mPRvy7GxGegTTXt+vr+Ag+EYhsvBaQs2xmCg7TNM3Edz7FEA4utS0i+TSNZ0SBxVlXCPVSxnTIYqmlTwzqEpw71yyOAfuzk0NZCJpQBPnlSl2EV+OynIsNDNtl8cEpjD5fLMLBUlWuMVDg4m2jeojwzjmiyphZhlomk7tJQJYbZRiP+xn5ltMYlQ3zTILN6EEgFXKAxrHFDp337HvIUjyyJ0JbMfq1PImMZl3bxQGY6tQ6Nzy7ogoBuBVNOjtKJ/g9RKel8wMp2zQOZg5pkohC2SrtmI5HgcICryI0ZDHmr9Q3cPNuL0sEn7borqBSBdOZGQFZHvc8lWolqLoHzCgl2wxwlebax8kky5cyHw4CmQ/7JbHSKW3PAjyU7kaVtyH0xRgr6AzRB4PKKI8LI7Vhm1LZ+hZUifQc0HgEYc5GIxZCCoLW7JBRDPar7OzkcK2D3pDLRFwnmoQF3Qv7A4Rix3ofQbz5W9vbJA2GenXewrniNVsLxRT44GXLfJD388R9sRLtBD98X+KbXLJsiREGX83wDQq3DwF6TI2L136e7+MFLgTXv/H0Ws2R8ASVYi0g6FDkKDjhUbTVoGMdu6LOFDZeRbDyHJeY5naaPyb0ioEnhkHEh8g8l06iMs6kURthEhArIgPLMIHXeGQlhXVH04RQyMk31iOeAJ6gnJqFu1e3uglNxkwGy5UGfvNr9PaKbFaQHFThKYMoODGap8vRhJwc7n/WpN1HZj50Q/lioH21dIM75CAtkbHLSU7tSyYZ8PSh+sDRPQ/fj1Tj+UYWCkBHawyuGUbNftyPhyxT5IgnUjGeLEoS4PUn41mY/amZFkmwtB7A9WtEV5gJsDf9OeVMKjZdT2OqtEBdmLcRiyUeLP4q4mSLguhl7j84j311fWRNDQdoMJNhp9LSITWCq32UlgmhiUhmU/6n5/tF8ruPXyUb5bHehBf6pYBHF5oH8YNG8MIpnaFIRrjONC4fjEnUoMfnkkWLs2uVUcMizeMhmdTeKsiG7N/Tbr+71R30u4PeYHOwudcf7OzudAfbe4PNwd5mb7M72Njq721t7+xud/u9BSpeGxTrXHxXJB9ePJ9ORGZsQpGRWIy9i90mWtGA3VE0ZyJeWpazK1GE4Rx6JkJRdVO82OdGR6ug9OaPlUs+pAk9p9GUJysdspIxMBKT8bkecIHCP69OW3JXyNZQ+CEVwgL7Z6oSFgD+VAobiPIDq4VVIrxUxbCKx7NUDQsgfyqH91EOCzq+YvWwQPLHVhALOvwQKuJTaBB+3NNzVA7aB908gOZgoXutSkEZv2d53pdBfPyj3M7/85See0pbEr3UA9gVPH9eZ2t7SXfPg9dF6fwIZ6qi2ZipH9I1YVB/pn4JA91z1TuewClhKPJalY9FKfAs1ZNFkXiWvggD4U8V5z6OCEPEl6oEtcfwmalJj+yCMER4xbqSHyx1Tsc2k8cLmSLFty0Cp3AMGz6VQEo/lPydMoyNp2SYiWsvu9rt7rMJm5lsFDkR10SfRAm5ZkObGgy5K3oonoyLQHtTEyB3oNog9/vHOkVMT/tYYtzMVl1j/nkiEnaL7bIUgAqS1qUOHdGMl4BaID/r6VS5xOOW8xK3VDH8IP7kcUzXt4IeWcU1+G/k4PNXsx7k0ynpD877GML5gYb6i3+ukf00jdnvbPh3rta3e1tBP+hvOThX//7b2YeTDr7zHyy8FGu2Bsl6fxD0yAcx5DFb728d9Td3DZHXt3ubpmOUI7UMRnTK42Ul0Hw6JTg+WbWRnxmLJlR1SMSGnCYdMsoYG8qoQ655EolruVYjID5Zg7tdhuXzNL0/YeWNZGzUQ2sOJH5isusAkkEFL1SCa9yFDPNB/JtesSqNLlmWsGUZbTUccDYHNhYOodfz9sVmsBn0uv3+oAt1QnlYhf4ZmnP3XmFbZsBb33lL+s8qPawJ8VjraeczezdkiRKyQ/Jhnqj8pv1Ks2te268asKWZCRKD3y/MPKbyAlgLVLGxyPif+ISoIskTJdzianFsjqxhJmgE1QJZFmrFH+QYZ9KzIT65xyUjIxHH4lqPbNoMFrnSkAm36koRrb0lMU/y7x0ypSFQNOHfi2QNQ9d62YhPp2Qm8jdvMn3CU8jLgBQAk3ZkkoFjLlXHpPl7eR5YWsANmYo01zZUFJDPMaOSkZgpkkvIiCDDmSZUomegCVYHxamODk47mqppJlIhGeFefiCNImghWY/pBzTbaspCBsutflXj87YCq98L+tUDdLmgemXFblGj9KHvKeFXsTkwjfr9j5P9j20Ub/2cVblpVuRwGhNyRnZ7g6D/jSg6XpVrmDyW0vCSKVfwSGLuB5WEJ2MoZQLNNvBPGJ9KKUJuivfpIRKb3A22Oxj3Gmu3MamrKGwmwyPRNpp0O+Uj5rgHGvsmLDIWiizSw/FkHBtsFR1DmhlIhxzKQUB3S7t4EyyAoAH91uVJ9xthSUhTmSOUsmNcD02QkVLeupqlPPTy3Uy2BZR4oS5BX7JEioyssmAckP/N2GWH/M4zJic0u1yD7HN+xeIZceYZOJoyOoKCyxVK8CRh2dxVxSEIPmSQKxZYklWbR2JGNb+V8V+bg+TN6CF+ZtxFsbwBPZR2f7HiPJ45+csTJ6E07kkDr2hGx2ZHzJJD0fEYZIEZ8tPQdiPzmNtyb+BzuTkFGvjPPm6GdLztu5agVovbFaYOmXVIRVyGGQMHWHWHmTEBAm+8eesy4hm7pnEsOyQD5pcd9IDQiAxpTJOQZfIB7N+lOWEB0eNDNCw0qxRlrN2q1OV427Noiebxp9QU9QQMwPW0CA4iV5JHtxRId6dBHicso0PuCs7aY6H2w/zzQR8PpYFaZLbRhqlJLc3NdpwuHFP3SitDhW+pJSGgE5UYWQVCy/8snHDFsI0XIKhq9KIQhiSLfN8zUBxN0RWrbXedPFgd+bckh2AF67lOv54erek/sL9CDA+6QYsXbDFGkZH3Zp+vlTJVi2bX33Iaz+Q4p1kU4N9QJPzbNRtOWJyuj8Q5VAaK17V+GLNozPTQ6yUEz62uzWQwUdM//icM5AArE6N49l9rjXVhbI0rm4tYVyvf/LFi8VrgJjeM9eFik8iXxCXQM6I0kauzWqKCDEVWaKKlxSl8PX45G+ghAi3Jwysp1+u1cv9x2rqwtwfxMzOza7T0vmgmJGw5c7JJd9DTGM5Mf9qmt+dsivCKBVOuMoYt4LVEWx/Rb8Dc8S/hFTuHhNtzDzh5HmZMm1V/HECdeTetL2k5wxP76HsqpJYXB/848jH8V21VjxNtQ306JdikhgyC/iDY7vjlXMrkMLbgl88HC3T9ZtCyYdnbwspO71YK9CO8POXyhqWpb4mmJWrYE0dtSbA0PUVjbjE2AmH1+HDNFhcwfThKRTmajk6COd4BOfbTsklevugzE5hB7a10na7VM6Mt619PqDrn8lxvAR6tGV6v8njhGKjy+vHhvxrWqIuNj3q9XuvmN1DZky2vbPk+yRiWVZsvYEpatpE2WGp1yhUfo5HkaGEXw3F/VFmXKmGaVyQc8+6QJ/pb8AqHY/43/cevjo7b/f4CZNSMd75U5je2psiIDGnSzKqNrbD6vf5usAhT6PETlgVXLInEsgq+n5liMfOOdQCBIAg1tM5YQodx++5GochYMCz64tyEzCgWtPEYfXOqh8GKERlNxuYWtRf0tP7d7wU9U/dF/0mGzN5CTIVURLIrlvm1Bd9pxVKaEYW2UbWeJiWTcgrXtiC101hwZYkyZSrjoSSrVCkaXpIrCPEp/J5Y1u87V7MOSTN+xWM2ZqbqsYnrUCzDktBrHcKnKQ1VMaofpaHHcOPq18YZDKuHMvFWAJPpBAuFqOcoAQ1Kl1XQgXW7kQhzjfJaTT/dCrYWW2KWXPFMJHq0Vrefj7TWRz5Yty06TWbEFa0ELjEr1CF3WSG42+cZ0+PLZ7BEik1TkT2n1TkzEN22MHCFOKUqR0JrkkbcK6TVKZ3Xdq3Ch9sXLSm8XI86mO8fbUOVkv+jMJhXP/7jcK047KHqmIKO1o5GsAzAnzS55MkYHNkrJ+J6pUNWPrCI59MV5OaV3/h4sgJLoI0zcjXQi+rEpxsROEFW3ZQQQVjMpWCqYqyNoGeqV83A0xixEU/KZXn1CMXDpTXyuAie4JKI64RFqL3QhI7RE/X++MvpWfApG2MPHbIKX2jhSb6edrHpfyKSbpqJEfdMLa97TYdcT4QWBlzaWtpKkAmLU5D74HeXLATm1JotyAmtfaUi8frBKUanktAwExIV52uRxdEcFk2uoiDhUgVjcQWeiq4RRcCudWGAVyjtWNUsyRK1C7fqjRoG1H3S1ANBYQ9BCq3goP967GiWZlxkXJmFIBkb0wxiDDwRcDcK1pR4PU3opr7FK/l9q7fnOyOhcc5BpSP8jfdVXGotIMbDAW9q0BLRG8u6J/Vm+V5p2y9LrTl9vyXHbh/xjMRiPDZdJcjZySnRwhTveyI+5nAS2oZ9RRc+RxEW5krreGTIE5pxrcecrn84/nBUni0xUe9DEcEzcIDSeCahnDIUardQCvD7X7o9+7ut5u73QMPAWIkdLvTbHajg7W6DISLwQv8AzZEuAhjGjDihcsKk5bfDoy9dluhTo9yFX4sZF7Nu2g7oNy+g+wsUxy9dwgxZcdnsbgfxdgsB0S8HckIHW9sXaw69oyuzqFQVgbh+P92as9neMBXXb7JTBsWSAls0IT38OpXGHa1X2ziwyIWKZeC1k7ow7SPMiPBzGHOWKEPQ+9+V0Bg2sD5uIKNhWfGirieX6ZvnzWvqYK6e7n9cCzCST88jyRXNZvpECCvbFNQG2yoUFQhvrcDlM4Ren3p7QhQnrmjRRENz/+HHU+JjTMiqHsqWsZZGXS8lirB6Z9A3f/WqfrfWPkwr7yfpROkaUd6th3tDq/7FW/Q7/J+iO6Wsota+PaWB+zl0pFxs9bAhpWs4qVWrDvn09ddKW3poQXnDSru9ctcVfzadKD9optBS4R+cXS+IxFM3n7zbxj1Ownvg+Qx6UC6GdoWzF0T9lfaqTIQ6hzY0LdCJivO2bC/wKSPQ4YeHk5pSiK0AYpGMmengHUFF6ysa86jB5zrodXs73f426W287W+93dj7r73e2/b5PhohvKdaJkbge2iDTX+v29sFbPpvN3tvB1uLYeO1k192b/B910DfBgzhBb+q9dyvYrlA920PnzDPrpa1ieACXI+PuJhwFhbH+oHQ/OQ11PdannuWGcFu8pYs1nlRw1/bqOnWoPUVgUcE9j0VSbumU15fkxKuR2aIouMFy6D0eHnRMLihHULbW1sbO848jdj3SqS5CM8xvqwagd4eccn/bLP485AGFwX/012AeGspUxpqA40Muapr54Pe5m57N0vGabzc1r0mSRKnsnemcOQ4tm0+3cBlAgJIKpaEvj97ZG6yoYQ7rHg6oQl23e0QrrzYcLRilfE0CDCSYq1YwLVHmmLIuBu66OpXI+zW1vt37/YOdg6P3r3v7e329g77g4OD/fZ9+a07Y+mC7ricMl1q4m6B8CXC7wxCJ6dTBldBfhF6PJKt+4X8hyAnNBmTg2yWKkFiPsxoNgvIKWPuJnXM1SQfQnzTWMQ0Ga+PxfowFsP1segH/c11mYXrIQywrm16+F8wFr+cbGzsdE82tuo9ibRavrXdXUAM2wbcT2JuSmdvzuuZfv+W9w6/pzAn725NWrifgzlZFT3WUaM3z1x78vTs10IH7ZCTX0v9/T17E335YF0+2Go/G1OyhPSiWDy1LTlvU5YW7j5IPQPDsYJjazReqRFoG+MvVdPxsonQAw6qR43NNm4CuqtnfkuGDK62aRJORIYfu6GNeDT3Oe/wmRII/x3GPrCdl8yZpF939xP2agFuQuPYNLcE97MGtdFjDilREyGVJ6iRTjTmrnllStXEPuw92ACg/nfI0oyFcGvRhZuD4kW4poFPvJwdRRObnlWCT+MXKD5lf9r8+/ngYRR85eEpH2Ncprk6KI2OFCkNK2CzmK/ww3kT38xB3a0PhN1AKMA4z2BRcLIm/FqQXq+Q/9yNaMGgd13TG0fWxNXqPpMBT6TynKi30gjcEvguse8SHtltEcYij4odcKA/2jiCjEyZohFVtHlTfDC/YjBIWHoVAg4Le4RG0Tk8cG6H1E+GTEoMNvP3SAlzeCngUzr26t7Ou5vy651MeZcOw6g/2GiULAXrHOuxyfGhC3RERCytUNj8Qvb1EsIzIo58DraQasQCBNcS4VZw53FH4zA3cog3u4X8vAW9bgbA0cCNtDAMJal1Tyja7hYPjikNJzxh514q913BMEP5WeFtofDDw849IXlXUOaN1xaeNBMgYO/NIGagxfkjY+NCVb3r7KVBqjMb+RaJ8BJ2kBFwh/ZzgzTA30CB0gd9HDPo+g3SDX/TwkBORKbO8YgpFCOrV+B8XSfc5pz/Dqw2+BeX8uXBSnISD0AoC+Z+bCKgR8TmVxqXcM5UWnQuPhsIc28zLzhr5c12k959OtMblvxCzj4dfnpLfhPXWoOa0hTLKPytBktJlyE36zNk/sFE3OGEIASWp7WK8Zd5bGP4/Df7TG3o42QkfO42px70QbUyzmNo/X0jO5tz8ejg1E/Uts06ZcBCGcymsT0/MXOQZuhkTkTSLd6sFCAW8zp0ttoZ85eyVFzPDjEUImY0abkco4JWkMNUsEl9XiGDYc7j+pR1DnBqy0p/97Df21tpB86nUwIz+KFFzYCEImKN++YmWKTKmAon7YGxs2CV0GTmOPYyH7IsYQqiJgyH/t3/rmHc4nenhpZ1ymJQ4vPnzfK5eOlWGV0C+q7cWF2LVETNAmwhseDRJhXog6svu54qbzgN7jrTZxGRr8eHzRPxtDZP6av2Uxx/rs8AHoyUhg9HtmLE+mQiqh1P95zM1sKaM1nFZrz/hHbApgR9PeP/+z//V5riV3WQzGnz13ufa97P51OapjwZm2dX/tpSqHg4mXN4StM6yFDRFF2Szw5uD7Zm4CWLIa/o+YHuIGsGPGNpzEMqy6VSyb25txh3zqaJWBqL2bTiQbn/xMW4cyYG3+oojx8cZW/gOVPfov/edWI3rLnIifgIElQVNlu2HeaLkqNZnig+ZWv2aDenaHGuf3ZfNEBgfixOdOdIaTqBi7HJAx2/7Htb08HMHRSB8TeYD9VpxHXCstpEPoC1FbKUgVfLCl3xRhUt0pQIfhtjkJvc742wtarKXIamwqT3hqepSEN1zlLVhPKsjT8lIptWwlEa0W9Za9n+K3yQUA3/L3an/FvE4pLTLs2ViLiErLdi2/wP/JUcml9mxH+OeL7AWz2xDUP5erOBww05747CPBegq7qc5HbbXmzltLe3OyaCRYwcaF7FuGZoWnuuWgFyRMOJqZ88oaXqBCaaL6QJGTLCuJoUaxGRKMdSKIpmKk8tT+BAHAq8T7EwgruQgOSPlGZ0ypRGOTPJkrDWTIFJjq3v4Qv9sWOy7wE0SLGisR5CSQxpOv6MTxiBRXjUgbwYyJ4sgQS5VkoCZZqJa9JG0kxEedjWCG9FYoiuc2eNmUCbiQ7rmwBaAvOVAHojXUnFVQ+mtVuA8rL1HwwmHNUFUziSeZwl9SEMpS550gxhns3JaLs7XF+/nJCJuMYwMQTE7AqA8aYlDPOMtd2vZXfMHHh+nzDYiAVNrql0m8w4tWiuJvq8ssWMMpII5TwSozyBhCtzLWyE8Pvyt/70npD8/wEAAP//zsM1NQ==" -} diff --git a/x-pack/functionbeat/magefile.go b/x-pack/functionbeat/magefile.go deleted file mode 100644 index 5df39f8c3c88..000000000000 --- a/x-pack/functionbeat/magefile.go +++ /dev/null @@ -1,234 +0,0 @@ -// Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one -// or more contributor license agreements. Licensed under the Elastic License; -// you may not use this file except in compliance with the Elastic License. - -//go:build mage - -package main - -import ( - "fmt" - "os" - "path/filepath" - "runtime" - "time" - - "github.com/magefile/mage/mg" - - devtools "github.com/elastic/beats/v7/dev-tools/mage" - "github.com/elastic/beats/v7/dev-tools/mage/target/build" - functionbeat "github.com/elastic/beats/v7/x-pack/functionbeat/scripts/mage" - - // mage:import - _ "github.com/elastic/beats/v7/dev-tools/mage/target/common" - // mage:import - _ "github.com/elastic/beats/v7/dev-tools/mage/target/pkg" - // mage:import - _ "github.com/elastic/beats/v7/dev-tools/mage/target/unittest" - // mage:import - _ "github.com/elastic/beats/v7/dev-tools/mage/target/integtest/notests" - // mage:import - _ "github.com/elastic/beats/v7/dev-tools/mage/target/test" -) - -func init() { - devtools.BeatDescription = "Functionbeat is a beat implementation for a serverless architecture." - devtools.BeatLicense = "Elastic License" -} - -// Build builds the Beat binary and functions by provider. -func Build() error { - params := devtools.DefaultBuildArgs() - - // Building functionbeat manager - err := devtools.Build(params) - if err != nil { - return err - } - - // Getting selected cloud providers - selectedProviders, err := functionbeat.SelectedProviders() - if err != nil { - return err - } - - // Building functions to deploy - for _, provider := range selectedProviders { - if !provider.Buildable { - continue - } - - inputFiles := filepath.Join("provider", provider.Name, "main.go") - params.InputFiles = []string{inputFiles} - params.Name = devtools.BeatName + "-" + provider.Name - params.OutputDir = filepath.Join("provider", provider.Name) - params.CGO = false - params.Env = make(map[string]string) - if provider.GOOS != "" { - params.Env["GOOS"] = provider.GOOS - } - if provider.GOARCH != "" { - params.Env["GOARCH"] = provider.GOARCH - } - err := devtools.Build(params) - if err != nil { - return err - } - } - return nil -} - -// GolangCrossBuild build the Beat binary inside of the golang-builder. -// Do not use directly, use crossBuild instead. -func GolangCrossBuild() error { - return devtools.GolangCrossBuild(devtools.DefaultGolangCrossBuildArgs()) -} - -// BuildGoDaemon builds the go-daemon binary (use crossBuildGoDaemon). -func BuildGoDaemon() error { - return devtools.BuildGoDaemon() -} - -// CrossBuild cross-builds the beat for all target platforms. -func CrossBuild() error { - - // Building functionbeat manager - err := devtools.CrossBuild() - if err != nil { - return err - } - - // Getting selected cloud providers - selectedProviders, err := functionbeat.SelectedProviders() - if err != nil { - return err - } - - // Building functions to deploy - for _, provider := range selectedProviders { - if !provider.Buildable { - continue - } - - if runtime.GOARCH != "amd64" { - fmt.Println("Crossbuilding functions only works on amd64 architecture.") - return nil - } - - err := devtools.CrossBuild(devtools.AddPlatforms("linux/amd64"), devtools.InDir("x-pack", "functionbeat", "provider", provider.Name)) - if err != nil { - return err - } - } - return nil -} - -// CrossBuildGoDaemon cross-builds the go-daemon binary using Docker. -func CrossBuildGoDaemon() error { - return devtools.CrossBuildGoDaemon() -} - -// Update is an alias for update:all. This is a workaround for -// https://github.com/magefile/mage/issues/217. -func Update() { mg.Deps(functionbeat.Update.All) } - -// Fields is an alias for update:fields. This is a workaround for -// https://github.com/magefile/mage/issues/217. -func Fields() { mg.Deps(functionbeat.Update.Fields) } - -// Config is an alias for update:config. This is a workaround for -// https://github.com/magefile/mage/issues/217. -func Config() { mg.Deps(functionbeat.Update.Config) } - -// AssembleDarwinUniversal merges the darwin/amd64 and darwin/arm64 into a single -// universal binary using `lipo`. It assumes the darwin/amd64 and darwin/arm64 -// were built and only performs the merge. -func AssembleDarwinUniversal() error { - return build.AssembleDarwinUniversal() -} - -// Package packages the Beat for distribution. -// Use SNAPSHOT=true to build snapshots. -// Use PLATFORMS to control the target platforms. -func Package() { - start := time.Now() - defer func() { fmt.Println("package ran for", time.Since(start)) }() - - devtools.MustUsePackaging("functionbeat", "x-pack/functionbeat/dev-tools/packaging/packages.yml") - - mg.Deps(Update) - mg.Deps(CrossBuild, CrossBuildGoDaemon) - mg.SerialDeps(devtools.Package, TestPackages) -} - -// Package packages the Beat for IronBank distribution. -// -// Use SNAPSHOT=true to build snapshots. -func Ironbank() error { - fmt.Println(">> Ironbank: this module is not subscribed to the IronBank releases.") - return nil -} - -// TestPackages tests the generated packages (i.e. file modes, owners, groups). -func TestPackages() error { - return devtools.TestPackages() -} - -// BuildPkgForFunctions creates a folder named pkg and adds functions to it. -// This makes testing the manager more comfortable. -func BuildPkgForFunctions() error { - mg.Deps(Update, Build) - - err := os.RemoveAll("pkg") - - filesToCopy := map[string]string{ - filepath.Join("provider", "aws", "functionbeat-aws"): filepath.Join("pkg", "functionbeat-aws"), - } - for src, dest := range filesToCopy { - c := &devtools.CopyTask{ - Source: src, - Dest: dest, - } - err = c.Execute() - if err != nil { - return err - } - } - return nil -} - -// BuildSystemTestBinary build a binary for testing that is instrumented for -// testing and measuring code coverage. The binary is only instrumented for -// coverage when TEST_COVERAGE=true (default is false). -func BuildSystemTestBinary() error { - err := devtools.BuildSystemTestBinary() - if err != nil { - return err - } - - params := devtools.DefaultTestBinaryArgs() - - // Getting selected cloud providers - selectedProviders, err := functionbeat.SelectedProviders() - if err != nil { - return err - } - - for _, provider := range selectedProviders { - if !provider.Buildable { - continue - } - - params.Name = filepath.Join("provider", provider.Name, devtools.BeatName+"-"+provider.Name) - inputFiles := make([]string, 0) - for _, inputFileName := range []string{"main.go", "main_test.go"} { - inputFiles = append(inputFiles, filepath.Join("provider", provider.Name, inputFileName)) - } - params.InputFiles = inputFiles - err := devtools.BuildSystemTestGoBinary(params) - if err != nil { - return err - } - } - return nil -} diff --git a/x-pack/functionbeat/main.go b/x-pack/functionbeat/main.go deleted file mode 100644 index 47c4c10ad4f6..000000000000 --- a/x-pack/functionbeat/main.go +++ /dev/null @@ -1,19 +0,0 @@ -// Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one -// or more contributor license agreements. Licensed under the Elastic License; -// you may not use this file except in compliance with the Elastic License. - -package main - -import ( - "os" - _ "time/tzdata" // for timezone handling - - _ "github.com/elastic/beats/v7/x-pack/functionbeat/include" // imports features - "github.com/elastic/beats/v7/x-pack/functionbeat/manager/cmd" -) - -func main() { - if err := cmd.RootCmd.Execute(); err != nil { - os.Exit(1) - } -} diff --git a/x-pack/functionbeat/main_test.go b/x-pack/functionbeat/main_test.go deleted file mode 100644 index 1c21f88e2891..000000000000 --- a/x-pack/functionbeat/main_test.go +++ /dev/null @@ -1,40 +0,0 @@ -// Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one -// or more contributor license agreements. Licensed under the Elastic License; -// you may not use this file except in compliance with the Elastic License. - -package main - -// This file is mandatory as otherwise the functionbeat.test binary is not generated correctly. - -import ( - "flag" - "testing" - - "github.com/elastic/beats/v7/libbeat/cfgfile" - "github.com/elastic/beats/v7/libbeat/tests/system/template" - "github.com/elastic/beats/v7/x-pack/functionbeat/manager/cmd" -) - -var systemTest *bool - -func init() { - testing.Init() - systemTest = flag.Bool("systemTest", false, "Set to true when running system tests") - - cmd.RootCmd.PersistentFlags().AddGoFlag(flag.CommandLine.Lookup("systemTest")) - cfgfile.AddAllowedBackwardsCompatibleFlag("systemTest") - cmd.RootCmd.PersistentFlags().AddGoFlag(flag.CommandLine.Lookup("test.coverprofile")) - cfgfile.AddAllowedBackwardsCompatibleFlag("test.coverprofile") -} - -// Test started when the test binary is started. Only calls main. -func TestSystem(t *testing.T) { - cfgfile.ConvertFlagsForBackwardsCompatibility() - if *systemTest { - main() - } -} - -func TestTemplate(t *testing.T) { - template.TestTemplate(t, cmd.Name, true) -} diff --git a/x-pack/functionbeat/make.bat b/x-pack/functionbeat/make.bat deleted file mode 100644 index 9fe6b2b801e2..000000000000 --- a/x-pack/functionbeat/make.bat +++ /dev/null @@ -1,11 +0,0 @@ -@echo off - -REM Windows wrapper for Mage (https://magefile.org/) that installs it -REM to %GOPATH%\bin from the Beats vendor directory. -REM -REM After running this once you may invoke mage.exe directly. - -WHERE mage -IF %ERRORLEVEL% NEQ 0 go install github.com/ph/functionbeat/vendor/github.com/magefile/mage - -mage %* diff --git a/x-pack/functionbeat/manager/aws/aws.go b/x-pack/functionbeat/manager/aws/aws.go deleted file mode 100644 index a8f2f5a5ad13..000000000000 --- a/x-pack/functionbeat/manager/aws/aws.go +++ /dev/null @@ -1,33 +0,0 @@ -// Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one -// or more contributor license agreements. Licensed under the Elastic License; -// you may not use this file except in compliance with the Elastic License. - -package aws - -import ( - "github.com/elastic/beats/v7/libbeat/feature" - "github.com/elastic/beats/v7/x-pack/functionbeat/function/provider" - "github.com/elastic/beats/v7/x-pack/functionbeat/provider/aws/aws" -) - -// Features exposes the trigger supported by the AWS provider. -var Features = provider.Builder( - "aws", - provider.NewDefaultProvider("aws", NewCLI, NewTemplateBuilder), - feature.MakeDetails("AWS Lambda", "listen to events on AWS lambda", feature.Stable), -).AddFunction("cloudwatch_logs", - aws.NewCloudwatchLogs, - aws.CloudwatchLogsDetails(), -).AddFunction("api_gateway_proxy", - aws.NewAPIGatewayProxy, - aws.APIGatewayProxyDetails(), -).AddFunction("kinesis", - aws.NewKinesis, - aws.KinesisDetails(), -).AddFunction("sqs", - aws.NewSQS, - aws.SQSDetails(), -).AddFunction("cloudwatch_logs_kinesis", - aws.NewCloudwatchKinesis, - aws.CloudwatchKinesisDetails(), -).Features() diff --git a/x-pack/functionbeat/manager/aws/cli_manager.go b/x-pack/functionbeat/manager/aws/cli_manager.go deleted file mode 100644 index 3bdb5ffa1ad4..000000000000 --- a/x-pack/functionbeat/manager/aws/cli_manager.go +++ /dev/null @@ -1,240 +0,0 @@ -// Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one -// or more contributor license agreements. Licensed under the Elastic License; -// you may not use this file except in compliance with the Elastic License. - -package aws - -import ( - "context" - "fmt" - "os" - "strings" - - "github.com/aws/aws-sdk-go-v2/aws" - cf "github.com/aws/aws-sdk-go-v2/service/cloudformation" - "github.com/awslabs/goformation/v7/cloudformation" - "github.com/awslabs/goformation/v7/cloudformation/iam" - "github.com/awslabs/goformation/v7/cloudformation/lambda" - - "github.com/elastic/beats/v7/x-pack/functionbeat/function/provider" - "github.com/elastic/beats/v7/x-pack/functionbeat/manager/core" - "github.com/elastic/beats/v7/x-pack/functionbeat/manager/executor" - fnaws "github.com/elastic/beats/v7/x-pack/functionbeat/provider/aws/aws" - awscommon "github.com/elastic/beats/v7/x-pack/libbeat/common/aws" - conf "github.com/elastic/elastic-agent-libs/config" - "github.com/elastic/elastic-agent-libs/logp" -) - -const ( - // AWS lambda currently support go 1.x as a runtime. - runtime = "go1.x" - handlerName = "functionbeat-aws" -) - -// AWSLambdaFunction add 'dependsOn' as a serializable parameters, goformation doesn't currently -// serialize this field. -type AWSLambdaFunction struct { - *lambda.Function - DependsOn []string -} - -type installer interface { - Policies() []iam.Role_Policy - Template() *cloudformation.Template - LambdaConfig() *fnaws.LambdaConfig -} - -// CLIManager interacts with the AWS Lambda API to deploy, update or remove a function. -// It will take care of creating the main lambda function and ask for each function type for the -// operation that need to be executed to connect the lambda to the triggers. -type CLIManager struct { - templateBuilder *defaultTemplateBuilder - awsCfg aws.Config - log *logp.Logger - config *fnaws.Config -} - -// stackName cloudformation stack are unique per function. -func (c *CLIManager) stackName(name string) string { - return "fnb-" + name + "-stack" -} - -func (c *CLIManager) deployTemplate(update bool, name string) error { - templateData, err := c.templateBuilder.execute(name) - if err != nil { - return err - } - - c.log.Debugf("Using cloudformation template:\n%s", templateData.json) - - _, err = c.awsCfg.Credentials.Retrieve(context.Background()) - if err != nil { - return fmt.Errorf("failed to retrieve aws credentials, please check AWS credential in config: %w", err) - } - - svcCF := cf.NewFromConfig(c.awsCfg) - - executer := executor.NewExecutor(c.log) - _ = executer.Add(newOpEnsureBucket(c.log, c.awsCfg, c.bucket())) - _ = executer.Add(newOpUploadToBucket( - c.log, - c.awsCfg, - c.bucket(), - templateData.codeKey, - templateData.zip.content, - )) - _ = executer.Add(newOpUploadToBucket( - c.log, - c.awsCfg, - c.bucket(), - templateData.key, - templateData.json, - )) - if update { - _ = executer.Add(newOpUpdateCloudFormation( - c.log, - svcCF, - templateData.url, - c.stackName(name), - )) - } else { - _ = executer.Add(newOpCreateCloudFormation( - c.log, - svcCF, - templateData.url, - c.stackName(name), - )) - } - - _ = executer.Add(newOpWaitCloudFormation(c.log, cf.NewFromConfig(c.awsCfg))) - _ = executer.Add(newOpDeleteFileBucket(c.log, c.awsCfg, c.bucket(), templateData.codeKey)) - - ctx := newStackContext() - if err := executer.Execute(ctx); err != nil { - if rollbackErr := executer.Rollback(ctx); rollbackErr != nil { - return fmt.Errorf("could not rollback, error: %s, %w", rollbackErr.Error(), err) - } - return err - } - return nil -} - -// Deploy uploads the function to AWS. -func (c *CLIManager) Deploy(name string) error { - c.log.Debugf("Deploying function: %s", name) - defer c.log.Debugf("Deploy finish for function '%s'", name) - - if err := c.deployTemplate(false, name); err != nil { - return err - } - c.log.Debugf("Successfully created function '%s'", name) - return nil -} - -// Update updates lambda using cloudformation. -func (c *CLIManager) Update(name string) error { - c.log.Debugf("Starting updating function '%s'", name) - defer c.log.Debugf("Update complete for function '%s'", name) - - if err := c.deployTemplate(true, name); err != nil { - return err - } - - c.log.Debugf("Successfully updated function: '%s'", name) - return nil -} - -// Remove removes a stack and unregister any resources created. -func (c *CLIManager) Remove(name string) error { - c.log.Debugf("Removing function: %s", name) - defer c.log.Debugf("Removal of function '%s' complete", name) - - _, err := c.awsCfg.Credentials.Retrieve(context.Background()) - if err != nil { - return fmt.Errorf("failed to retrieve aws credentials, please check AWS credential in config: %w", err) - } - - svc := cf.NewFromConfig(c.awsCfg) - executer := executor.NewExecutor(c.log) - _ = executer.Add(newOpDeleteCloudFormation(c.log, svc, c.stackName(name))) - _ = executer.Add(newWaitDeleteCloudFormation(c.log, c.awsCfg)) - - ctx := newStackContext() - if err := executer.Execute(ctx); err != nil { - if rollbackErr := executer.Rollback(ctx); rollbackErr != nil { - return fmt.Errorf("could not rollback, error: %s, %w", rollbackErr.Error(), err) - } - return err - } - return nil -} - -// Export prints the exported function data. -func (c *CLIManager) Export(name string) error { - tmpl, err := c.templateBuilder.RawTemplate(name) - if err != nil { - return err - } - - fmt.Println(tmpl) //nolint:forbidigo // standalone tool - - return nil -} - -// Package packages functions for AWS. -func (c *CLIManager) Package(outputPattern string) error { - resource := zipResources() - content, err := core.MakeZip(packageUncompressedLimit, packageCompressedLimit, resource) - if err != nil { - return err - } - - output := strings.ReplaceAll(outputPattern, "{{.Provider}}", "aws") - err = os.WriteFile(output, content, 0644) - if err != nil { - return err - } - - _, _ = fmt.Fprintf(os.Stderr, "Generated package for provider aws at: %s\n", output) - return nil -} - -func (c *CLIManager) bucket() string { - return string(c.config.DeployBucket) -} - -// NewCLI returns the interface to manage function on Amazon lambda. -func NewCLI( - log *logp.Logger, - cfg *conf.C, - provider provider.Provider, -) (provider.CLIManager, error) { - config := fnaws.DefaultConfig() - if err := cfg.Unpack(config); err != nil { - return nil, err - } - awsCfg, err := awscommon.InitializeAWSConfig(config.Credentials) - if err != nil { - return nil, fmt.Errorf("failed to get aws credentials, please check AWS credential in config: %w", err) - } - if config.Region != "" { - awsCfg.Region = config.Region - } - - builder, err := provider.TemplateBuilder() - if err != nil { - return nil, err - } - - templateBuilder, ok := builder.(*defaultTemplateBuilder) - if !ok { - return nil, fmt.Errorf("not defaultTemplateBuilder") - } - - return &CLIManager{ - config: config, - awsCfg: awsCfg, - log: logp.NewLogger("aws"), - templateBuilder: templateBuilder, - }, nil -} diff --git a/x-pack/functionbeat/manager/aws/cli_manager_test.go b/x-pack/functionbeat/manager/aws/cli_manager_test.go deleted file mode 100644 index 336f979587f8..000000000000 --- a/x-pack/functionbeat/manager/aws/cli_manager_test.go +++ /dev/null @@ -1,38 +0,0 @@ -// Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one -// or more contributor license agreements. Licensed under the Elastic License; -// you may not use this file except in compliance with the Elastic License. - -package aws - -import ( - "testing" - - "github.com/stretchr/testify/assert" - - "github.com/elastic/beats/v7/libbeat/common" -) - -func TestChecksum(t *testing.T) { - t.Run("same bytes content return the same key", func(t *testing.T) { - content, err := common.RandomBytes(100) - if !assert.NoError(t, err) { - return - } - - assert.Equal(t, checksum(content), checksum(content)) - }) - - t.Run("different bytes return a different key", func(t *testing.T) { - content, err := common.RandomBytes(100) - if !assert.NoError(t, err) { - return - } - - other, err := common.RandomBytes(100) - if !assert.NoError(t, err) { - return - } - - assert.NotEqual(t, checksum(content), checksum(other)) - }) -} diff --git a/x-pack/functionbeat/manager/aws/cloudformation_interface.go b/x-pack/functionbeat/manager/aws/cloudformation_interface.go deleted file mode 100644 index 46d03734c958..000000000000 --- a/x-pack/functionbeat/manager/aws/cloudformation_interface.go +++ /dev/null @@ -1,24 +0,0 @@ -// Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one -// or more contributor license agreements. Licensed under the Elastic License; -// you may not use this file except in compliance with the Elastic License. - -package aws - -import ( - "context" - - "github.com/aws/aws-sdk-go-v2/service/cloudformation" -) - -type deleteStackClient interface { - cloudformation.DescribeStacksAPIClient - DeleteStack(ctx context.Context, params *cloudformation.DeleteStackInput, optFns ...func(*cloudformation.Options)) (*cloudformation.DeleteStackOutput, error) -} - -type createStackClient interface { - CreateStack(ctx context.Context, params *cloudformation.CreateStackInput, optFns ...func(*cloudformation.Options)) (*cloudformation.CreateStackOutput, error) -} - -type updateStackClient interface { - UpdateStack(ctx context.Context, params *cloudformation.UpdateStackInput, optFns ...func(*cloudformation.Options)) (*cloudformation.UpdateStackOutput, error) -} diff --git a/x-pack/functionbeat/manager/aws/event_stack_poller.go b/x-pack/functionbeat/manager/aws/event_stack_poller.go deleted file mode 100644 index 6b3b58ae79fb..000000000000 --- a/x-pack/functionbeat/manager/aws/event_stack_poller.go +++ /dev/null @@ -1,157 +0,0 @@ -// Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one -// or more contributor license agreements. Licensed under the Elastic License; -// you may not use this file except in compliance with the Elastic License. - -package aws - -import ( - "context" - "sync" - "time" - - "github.com/aws/aws-sdk-go-v2/service/cloudformation/types" - - "github.com/aws/aws-sdk-go-v2/service/cloudformation" - - "github.com/elastic/elastic-agent-libs/logp" -) - -// Resource type to look for. -const eventAWSCloudFormationStack = "AWS::CloudFormation::Stack" - -type eventStackHandler interface { - sync(event types.StackEvent) bool - handle(event types.StackEvent) -} - -// eventStackPoller takes a stack id and will report any events coming from it. -// The event stream for a stack will return all the events for a specific existence of a stack, -// it's important to be able to skip some events and only report the meaningful events. -type eventStackPoller struct { - log *logp.Logger - svc cloudformation.DescribeStackEventsAPIClient - stackID *string - periodicCheck time.Duration - handler eventStackHandler - done chan struct{} - wg sync.WaitGroup -} - -func newEventStackPoller( - log *logp.Logger, - svc cloudformation.DescribeStackEventsAPIClient, - stackID *string, - periodicCheck time.Duration, - handler eventStackHandler, -) *eventStackPoller { - return &eventStackPoller{ - log: log, - svc: svc, - stackID: stackID, - periodicCheck: periodicCheck, - handler: handler, - done: make(chan struct{}), - } -} - -func (e *eventStackPoller) Start() { - e.wg.Add(1) - go func() { - defer e.wg.Done() - e.poll() - }() -} - -func (e *eventStackPoller) Stop() { - close(e.done) - e.wg.Wait() -} - -func (e *eventStackPoller) poll() { - var nextToken *string - var foundFirstEvent bool - var alreadyLoggedEvents = make(map[string]struct{}) - for { - input := &cloudformation.DescribeStackEventsInput{ - NextToken: nextToken, - StackName: e.stackID, - } - - // Currently no way to skip items based on time. - // doc: https://docs.aws.amazon.com/AWSCloudFormation/latest/APIReference/API_DescribeStackEvents.html - resp, err := e.svc.DescribeStackEvents(context.TODO(), input) - if err != nil { - // This is not a fatal error because the check is made out of bound from the current status logic. - // I wanted to keep them separate so it is easier to deal with states and reporting. - e.log.Errorf("Could not retrieve the events for stack, error: %+v", err) - } - - // Events are in reverse order. we need older -> new, but we do not rely on the time but just - // the position in the slice. - for i, j := 0, len(resp.StackEvents)-1; i < j; i, j = i+1, j-1 { - resp.StackEvents[i], resp.StackEvents[j] = resp.StackEvents[j], resp.StackEvents[i] - } - - for _, event := range resp.StackEvents { - // Since we receive all the events from the beginning of the stack we have - // to first position ourself to an event of interest. - if !foundFirstEvent { - if !e.handler.sync(event) { - // keep current event and position to the first meaningful event. - foundFirstEvent = true - } else { - //discard current event. - continue - } - } - - // When the stack is in progress we will receive an empty token, so we have to make another - // call with the current token this mean we probably have already see the events so we have to - // ignore them. I am using ids here instance of time because I think 2 events might have - // the same time. I am assuming this map should stay relatively small. - if _, ok := alreadyLoggedEvents[*event.EventId]; ok { - continue - } - - e.handler.handle(event) - alreadyLoggedEvents[*event.EventId] = struct{}{} - } - - select { - case <-e.done: - // if nextToken is nil it mean we are at the end of the current pages. - // if not it mean we still have log to get and we need to report them before quitting. - if nextToken == nil { - return - } - case <-time.After(e.periodicCheck): - } - } -} - -type reportStackEvent struct { - skipBefore time.Time - callback func(event types.StackEvent) -} - -func (r *reportStackEvent) sync(event types.StackEvent) bool { - // Ignore anything before the Start pointer and everything which is not AWS::CloudFormation::Stack - if r.skipBefore.Before(*event.Timestamp) && *event.ResourceType == eventAWSCloudFormationStack { - // We are only interested in events thats `START` a request. - switch event.ResourceStatus { - case types.ResourceStatusCreateInProgress: - return false - case types.ResourceStatusDeleteInProgress: - return false - case types.ResourceStatusUpdateInProgress: - return false - default: - return true - } - } - return true -} - -func (r *reportStackEvent) handle(event types.StackEvent) { - r.callback(event) -} diff --git a/x-pack/functionbeat/manager/aws/event_stack_poller_test.go b/x-pack/functionbeat/manager/aws/event_stack_poller_test.go deleted file mode 100644 index 3679f07fb547..000000000000 --- a/x-pack/functionbeat/manager/aws/event_stack_poller_test.go +++ /dev/null @@ -1,341 +0,0 @@ -// Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one -// or more contributor license agreements. Licensed under the Elastic License; -// you may not use this file except in compliance with the Elastic License. - -package aws - -import ( - "context" - "strconv" - "sync/atomic" - "testing" - "time" - - "github.com/aws/aws-sdk-go-v2/service/cloudformation/types" - - "github.com/aws/aws-sdk-go-v2/service/cloudformation" - "github.com/stretchr/testify/assert" - - "github.com/elastic/elastic-agent-libs/logp" -) - -type mockEventHandler struct { - skipEvents int32 - skipCount atomic.Int32 - events chan types.StackEvent -} - -func (m *mockEventHandler) sync(event types.StackEvent) bool { - if m.skipCount.Load() >= m.skipEvents { - return false - } - m.skipCount.Add(1) - return true -} - -func (m *mockEventHandler) handle(event types.StackEvent) { - m.events <- event -} - -type mockCloudFormationClient struct { - Responses []*cloudformation.DescribeStackEventsOutput - Index int -} - -func (m *mockCloudFormationClient) DescribeStackEvents(context.Context, *cloudformation.DescribeStackEventsInput, ...func(*cloudformation.Options)) (*cloudformation.DescribeStackEventsOutput, error) { - defer func() { - // This minic the fact that the last token will be nil. - if m.Index < len(m.Responses)-1 { - m.Index++ - } - }() - - return m.Responses[m.Index], nil -} - -func TestEventStackPoller(t *testing.T) { - t.Run("emits all events", testEmitAllEvents) - t.Run("skip events", testSkipEvents) - t.Run("skip duplicates", testSkipDuplicates) - t.Run("return time ordered events", testReturnTimeOrdered) -} - -func testEmitAllEvents(t *testing.T) { - response1 := &cloudformation.DescribeStackEventsOutput{ - NextToken: ptr("12345"), - StackEvents: []types.StackEvent{ - types.StackEvent{EventId: ptr("1"), Timestamp: ptrTime(time.Now())}, - types.StackEvent{EventId: ptr("2"), Timestamp: ptrTime(time.Now())}, - types.StackEvent{EventId: ptr("3"), Timestamp: ptrTime(time.Now())}, - types.StackEvent{EventId: ptr("4"), Timestamp: ptrTime(time.Now())}, - types.StackEvent{EventId: ptr("5"), Timestamp: ptrTime(time.Now())}, - }, - } - response2 := &cloudformation.DescribeStackEventsOutput{ - StackEvents: []types.StackEvent{ - types.StackEvent{EventId: ptr("6"), Timestamp: ptrTime(time.Now())}, - types.StackEvent{EventId: ptr("7"), Timestamp: ptrTime(time.Now())}, - types.StackEvent{EventId: ptr("8"), Timestamp: ptrTime(time.Now())}, - types.StackEvent{EventId: ptr("9"), Timestamp: ptrTime(time.Now())}, - types.StackEvent{EventId: ptr("10"), Timestamp: ptrTime(time.Now())}, - }, - } - - client := &mockCloudFormationClient{Responses: []*cloudformation.DescribeStackEventsOutput{ - response1, - response2, - }} - - handler := &mockEventHandler{events: make(chan types.StackEvent)} - poller := newEventStackPoller( - logp.NewLogger(""), - client, - ptr("1235"), - 1, - handler, - ) - poller.Start() - defer poller.Stop() - - var c int - for range handler.events { - c++ - if c == 10 { - return - } - } -} - -func testSkipEvents(t *testing.T) { - response1 := &cloudformation.DescribeStackEventsOutput{ - NextToken: ptr("12345"), - StackEvents: []types.StackEvent{ - types.StackEvent{EventId: ptr("1"), Timestamp: ptrTime(time.Now())}, - types.StackEvent{EventId: ptr("2"), Timestamp: ptrTime(time.Now())}, - types.StackEvent{EventId: ptr("3"), Timestamp: ptrTime(time.Now())}, - types.StackEvent{EventId: ptr("4"), Timestamp: ptrTime(time.Now())}, - types.StackEvent{EventId: ptr("5"), Timestamp: ptrTime(time.Now())}, - }, - } - response2 := &cloudformation.DescribeStackEventsOutput{ - StackEvents: []types.StackEvent{ - types.StackEvent{EventId: ptr("6"), Timestamp: ptrTime(time.Now())}, - types.StackEvent{EventId: ptr("7"), Timestamp: ptrTime(time.Now())}, - types.StackEvent{EventId: ptr("8"), Timestamp: ptrTime(time.Now())}, - types.StackEvent{EventId: ptr("9"), Timestamp: ptrTime(time.Now())}, - types.StackEvent{EventId: ptr("10"), Timestamp: ptrTime(time.Now())}, - }, - } - - client := &mockCloudFormationClient{Responses: []*cloudformation.DescribeStackEventsOutput{ - response1, - response2, - }} - - handler := &mockEventHandler{skipEvents: 3, events: make(chan types.StackEvent)} - poller := newEventStackPoller( - logp.NewLogger(""), - client, - ptr("1235"), - 0, - handler, - ) - poller.Start() - defer poller.Stop() - - var c int - for range handler.events { - c++ - if c == 7 { - return - } - } -} - -func testSkipDuplicates(t *testing.T) { - response1 := &cloudformation.DescribeStackEventsOutput{ - NextToken: ptr("12345"), - StackEvents: []types.StackEvent{ - types.StackEvent{EventId: ptr("1"), Timestamp: ptrTime(time.Now())}, - types.StackEvent{EventId: ptr("2"), Timestamp: ptrTime(time.Now())}, - types.StackEvent{EventId: ptr("3"), Timestamp: ptrTime(time.Now())}, - types.StackEvent{EventId: ptr("4"), Timestamp: ptrTime(time.Now())}, - types.StackEvent{EventId: ptr("4"), Timestamp: ptrTime(time.Now())}, - }, - } - response2 := &cloudformation.DescribeStackEventsOutput{ - StackEvents: []types.StackEvent{ - types.StackEvent{EventId: ptr("1"), Timestamp: ptrTime(time.Now())}, - types.StackEvent{EventId: ptr("2"), Timestamp: ptrTime(time.Now())}, - types.StackEvent{EventId: ptr("2"), Timestamp: ptrTime(time.Now())}, - types.StackEvent{EventId: ptr("4"), Timestamp: ptrTime(time.Now())}, - types.StackEvent{EventId: ptr("5"), Timestamp: ptrTime(time.Now())}, - }, - } - - client := &mockCloudFormationClient{Responses: []*cloudformation.DescribeStackEventsOutput{ - response1, - response2, - }} - - handler := &mockEventHandler{skipEvents: 3, events: make(chan types.StackEvent)} - poller := newEventStackPoller( - logp.NewLogger(""), - client, - ptr("1235"), - 0, - handler, - ) - poller.Start() - defer poller.Stop() - - var c int - for range handler.events { - c++ - if c == 4 { - return - } - } -} - -func testReturnTimeOrdered(t *testing.T) { - response1 := &cloudformation.DescribeStackEventsOutput{ - NextToken: ptr("12345"), - StackEvents: []types.StackEvent{ - types.StackEvent{EventId: ptr("5"), Timestamp: ptrTime(time.Now())}, - types.StackEvent{EventId: ptr("4"), Timestamp: ptrTime(time.Now())}, - types.StackEvent{EventId: ptr("3"), Timestamp: ptrTime(time.Now())}, - types.StackEvent{EventId: ptr("2"), Timestamp: ptrTime(time.Now())}, - types.StackEvent{EventId: ptr("1"), Timestamp: ptrTime(time.Now())}, - }, - } - - client := &mockCloudFormationClient{Responses: []*cloudformation.DescribeStackEventsOutput{ - response1, - }} - - handler := &mockEventHandler{events: make(chan types.StackEvent)} - poller := newEventStackPoller( - logp.NewLogger(""), - client, - ptr("1235"), - 0, - handler, - ) - poller.Start() - defer poller.Stop() - - c := 1 - for event := range handler.events { - if c == 5 { - return - } - - assert.Equal(t, strconv.Itoa(c), *event.EventId) - c++ - } -} - -func TestReportStackEvent(t *testing.T) { - t.Run("test skip event", testReportSkipEvents) - t.Run("test that handle forward the event to callback", testReportCallback) -} - -func testReportSkipEvents(t *testing.T) { - now := time.Now() - - tests := []struct { - name string - event types.StackEvent - sync bool - }{ - { - name: "is stack event but happened before", - event: types.StackEvent{ - ResourceType: ptr("AWS::CloudFormation::Stack"), - EventId: ptr("1"), - Timestamp: ptrTime(now.Add(-10 * time.Second)), - }, - sync: true, - }, - { - name: "is not a stack event", - event: types.StackEvent{ - ResourceType: ptr("AWS::S3::Bucket"), - EventId: ptr("2"), - Timestamp: ptrTime(now.Add(10 * time.Second)), - }, - sync: true, - }, - { - name: "is a stack event and happens after but with wrong status", - event: types.StackEvent{ - ResourceType: ptr("AWS::CloudFormation::Stack"), - ResourceStatus: types.ResourceStatusDeleteFailed, - EventId: ptr("2"), - Timestamp: ptrTime(now.Add(11 * time.Second)), - }, - sync: true, - }, - { - name: "is a stack event and happens after with a CREATE_IN_PROGRESS status", - event: types.StackEvent{ - ResourceType: ptr("AWS::CloudFormation::Stack"), - ResourceStatus: types.ResourceStatusCreateInProgress, - EventId: ptr("2"), - Timestamp: ptrTime(now.Add(11 * time.Second)), - }, - sync: false, - }, - { - name: "is a stack event and happens after with an UPDATE_IN_PROGRESS status", - event: types.StackEvent{ - ResourceType: ptr("AWS::CloudFormation::Stack"), - ResourceStatus: types.ResourceStatusUpdateInProgress, - EventId: ptr("2"), - Timestamp: ptrTime(now.Add(11 * time.Second)), - }, - sync: false, - }, - { - name: "is a stack event and happens after with an DELETE_IN_PROGRESS status", - event: types.StackEvent{ - ResourceType: ptr("AWS::CloudFormation::Stack"), - ResourceStatus: types.ResourceStatusDeleteInProgress, - EventId: ptr("2"), - Timestamp: ptrTime(now.Add(11 * time.Second)), - }, - sync: false, - }, - } - - reporter := reportStackEvent{ - skipBefore: now, - callback: func(event types.StackEvent) {}, - } - - for _, test := range tests { - t.Run(test.name, func(t *testing.T) { - assert.Equal(t, test.sync, reporter.sync(test.event)) - }) - } -} - -func testReportCallback(t *testing.T) { - var received bool - reporter := reportStackEvent{ - skipBefore: time.Now(), - callback: func(event types.StackEvent) { received = true }, - } - - reporter.handle(types.StackEvent{}) - assert.True(t, received) -} - -func ptr(v string) *string { - return &v -} - -func ptrTime(t time.Time) *time.Time { - return &t -} diff --git a/x-pack/functionbeat/manager/aws/op_cloudformation.go b/x-pack/functionbeat/manager/aws/op_cloudformation.go deleted file mode 100644 index 028c78cd4a4e..000000000000 --- a/x-pack/functionbeat/manager/aws/op_cloudformation.go +++ /dev/null @@ -1,110 +0,0 @@ -// Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one -// or more contributor license agreements. Licensed under the Elastic License; -// you may not use this file except in compliance with the Elastic License. - -package aws - -import ( - "context" - "fmt" - "strings" - "time" - - "github.com/aws/aws-sdk-go-v2/service/cloudformation/types" - - "github.com/aws/aws-sdk-go-v2/aws" - "github.com/aws/aws-sdk-go-v2/service/cloudformation" - "github.com/gofrs/uuid/v5" - - "github.com/elastic/beats/v7/x-pack/functionbeat/manager/executor" - "github.com/elastic/elastic-agent-libs/logp" -) - -type opCreateCloudFormation struct { - log *logp.Logger - svc createStackClient - templateURL string - stackName string -} - -func newOpCreateCloudFormation( - log *logp.Logger, - svc createStackClient, - templateURL, stackName string, -) *opCreateCloudFormation { - return &opCreateCloudFormation{ - log: log, - svc: svc, - templateURL: templateURL, - stackName: stackName, - } -} - -func (o *opCreateCloudFormation) Execute(ctx executor.Context) error { - c, ok := ctx.(*stackContext) - if !ok { - return errWrongContext - } - - o.log.Debug("Creating CloudFormation create stack request") - uuid, err := uuid.NewV4() - if err != nil { - return err - } - input := &cloudformation.CreateStackInput{ - ClientRequestToken: aws.String(uuid.String()), - StackName: aws.String(o.stackName), - TemplateURL: aws.String(o.templateURL), - Capabilities: []types.Capability{ - types.CapabilityCapabilityNamedIam, - }, - } - - resp, err := o.svc.CreateStack(context.TODO(), input) - if err != nil { - o.log.Debugf("Could not create the CloudFormation stack request, resp: %v", resp) - return err - } - - c.ID = resp.StackId - - return nil -} - -func makeEventStackPoller( - log *logp.Logger, - svc *cloudformation.Client, - periodicCheck time.Duration, - ctx *stackContext, -) *eventStackPoller { - return newEventStackPoller( - log, - svc, - ctx.ID, - periodicCheck, - &reportStackEvent{skipBefore: ctx.StartedAt, callback: func(event types.StackEvent) { - // Returned values for a stack events are hit or miss, so lets try to create a - // meaningful string. - var buf strings.Builder - fmt.Fprintf(&buf, "Stack event received") - - writeOptKV(&buf, "ResourceType", event.ResourceType) - writeOptKV(&buf, "LogicalResourceId", event.LogicalResourceId) - s := string(event.ResourceStatus) - writeOptKV(&buf, "ResourceStatus", &s) - writeOptKV(&buf, "ResourceStatusReason", event.ResourceStatusReason) - - log.Info(buf.String()) - }}, - ) -} - -func writeKV(buf *strings.Builder, key string, value string) { - fmt.Fprintf(buf, ", %s: %s", key, value) -} - -func writeOptKV(buf *strings.Builder, key string, value *string) { - if value != nil { - writeKV(buf, key, *value) - } -} diff --git a/x-pack/functionbeat/manager/aws/op_cloudformation_test.go b/x-pack/functionbeat/manager/aws/op_cloudformation_test.go deleted file mode 100644 index 767b638083b4..000000000000 --- a/x-pack/functionbeat/manager/aws/op_cloudformation_test.go +++ /dev/null @@ -1,211 +0,0 @@ -// Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one -// or more contributor license agreements. Licensed under the Elastic License; -// you may not use this file except in compliance with the Elastic License. - -package aws - -import ( - "context" - "errors" - "testing" - - "github.com/aws/aws-sdk-go-v2/service/cloudformation/types" - - "github.com/aws/aws-sdk-go-v2/service/cloudformation" - "github.com/stretchr/testify/assert" - - "github.com/elastic/elastic-agent-libs/logp" -) - -type mockCloudformationStack struct { - respCreateStackOutput *cloudformation.CreateStackOutput - onCreateStackInput func(*cloudformation.CreateStackInput) - - respDeleteStackOutput *cloudformation.DeleteStackOutput - onDeleteStackInput func(*cloudformation.DeleteStackInput) - - respDescribeStacksOutput *cloudformation.DescribeStacksOutput - onDescribeStacksInput func(*cloudformation.DescribeStacksInput) - - respUpdateStackOutput *cloudformation.UpdateStackOutput - onUpdateStackInput func(*cloudformation.UpdateStackInput) - err error -} - -func (m *mockCloudformationStack) CreateStack(ctx context.Context, params *cloudformation.CreateStackInput, optFns ...func(*cloudformation.Options)) (*cloudformation.CreateStackOutput, error) { - if m.onCreateStackInput != nil { - m.onCreateStackInput(params) - } - - if m.err != nil { - return m.respCreateStackOutput, m.err - } - - return m.respCreateStackOutput, nil -} - -func (m *mockCloudformationStack) DeleteStack(ctx context.Context, params *cloudformation.DeleteStackInput, optFns ...func(*cloudformation.Options)) (*cloudformation.DeleteStackOutput, error) { - if m.onDeleteStackInput != nil { - m.onDeleteStackInput(params) - } - - if m.err != nil { - return m.respDeleteStackOutput, m.err - } - - return m.respDeleteStackOutput, nil -} - -func (m *mockCloudformationStack) DescribeStacks(ctx context.Context, params *cloudformation.DescribeStacksInput, optFns ...func(*cloudformation.Options)) (*cloudformation.DescribeStacksOutput, error) { - if m.onDescribeStacksInput != nil { - m.onDescribeStacksInput(params) - } - - if m.err != nil { - return m.respDescribeStacksOutput, m.err - } - - return m.respDescribeStacksOutput, nil -} - -func (m *mockCloudformationStack) UpdateStack(ctx context.Context, params *cloudformation.UpdateStackInput, optFns ...func(*cloudformation.Options)) (*cloudformation.UpdateStackOutput, error) { - if m.onUpdateStackInput != nil { - m.onUpdateStackInput(params) - } - - if m.err != nil { - return m.respUpdateStackOutput, m.err - } - - return m.respUpdateStackOutput, nil -} - -func TestCreateStack(t *testing.T) { - stackName := "new-stack" - stackID := "new-stack-ID" - templateURL := "https://localhost/stack.zip" - log := logp.NewLogger("") - - t.Run("assert execution context", func(t *testing.T) { - op := &opCreateCloudFormation{} - err := op.Execute(struct{}{}) - assert.Error(t, err) - }) - - t.Run("create stack", func(t *testing.T) { - mockSvc := &mockCloudformationStack{respCreateStackOutput: &cloudformation.CreateStackOutput{ - StackId: &stackID, - }, onCreateStackInput: func(input *cloudformation.CreateStackInput) { - assert.Equal(t, stackName, *input.StackName) - assert.Equal(t, templateURL, *input.TemplateURL) - }} - - ctx := &stackContext{} - op := newOpCreateCloudFormation(log, mockSvc, templateURL, stackName) - err := op.Execute(ctx) - if !assert.NoError(t, err) { - return - } - - assert.Equal(t, stackID, *ctx.ID) - }) - - t.Run("bubble any stack error back to the caller", func(t *testing.T) { - anErr := errors.New("something is bad") - mockSvc := &mockCloudformationStack{err: anErr} - - ctx := &stackContext{} - op := newOpCreateCloudFormation(log, mockSvc, templateURL, stackName) - err := op.Execute(ctx) - assert.Equal(t, anErr, err) - }) -} - -func TestDeleteStack(t *testing.T) { - stackName := "new-stack" - stackID := "new-stack-ID" - log := logp.NewLogger("") - - t.Run("assert execution context", func(t *testing.T) { - op := &opDeleteCloudFormation{} - err := op.Execute(struct{}{}) - assert.Error(t, err) - }) - - t.Run("delete stack", func(t *testing.T) { - mockSvc := &mockCloudformationStack{ - respDeleteStackOutput: &cloudformation.DeleteStackOutput{}, - onDeleteStackInput: func( - input *cloudformation.DeleteStackInput, - ) { - assert.Equal(t, stackName, *input.StackName) - }, - respDescribeStacksOutput: &cloudformation.DescribeStacksOutput{ - Stacks: []types.Stack{types.Stack{StackId: &stackID}}, - }, - } - ctx := &stackContext{} - op := newOpDeleteCloudFormation(log, mockSvc, stackName) - err := op.Execute(ctx) - if !assert.NoError(t, err) { - return - } - - assert.Equal(t, stackID, *ctx.ID) - }) - - t.Run("bubble any stack error back to the caller", func(t *testing.T) { - anErr := errors.New("something is bad") - mockSvc := &mockCloudformationStack{err: anErr} - - ctx := &stackContext{} - op := newOpDeleteCloudFormation(log, mockSvc, stackName) - err := op.Execute(ctx) - assert.Equal(t, anErr, err) - }) -} - -func TestUpdateStack(t *testing.T) { - stackName := "new-stack" - stackID := "new-stack-ID" - templateURL := "https://localhost/stack.zip" - log := logp.NewLogger("") - - t.Run("assert execution context", func(t *testing.T) { - op := &opDeleteCloudFormation{} - err := op.Execute(struct{}{}) - assert.Error(t, err) - }) - - t.Run("update stack", func(t *testing.T) { - mockSvc := &mockCloudformationStack{ - onUpdateStackInput: func( - input *cloudformation.UpdateStackInput, - ) { - assert.Equal(t, stackName, *input.StackName) - assert.Equal(t, templateURL, *input.TemplateURL) - }, - respUpdateStackOutput: &cloudformation.UpdateStackOutput{ - StackId: &stackID, - }, - } - ctx := &stackContext{} - op := newOpUpdateCloudFormation(log, mockSvc, templateURL, stackName) - err := op.Execute(ctx) - if !assert.NoError(t, err) { - return - } - - assert.Equal(t, stackID, *ctx.ID) - }) - - t.Run("bubble any stack error back to the caller", func(t *testing.T) { - anErr := errors.New("something is bad") - mockSvc := &mockCloudformationStack{err: anErr} - - ctx := &stackContext{} - op := newOpUpdateCloudFormation(log, mockSvc, templateURL, stackName) - err := op.Execute(ctx) - assert.Equal(t, anErr, err) - }) -} diff --git a/x-pack/functionbeat/manager/aws/op_delete_cloudformation.go b/x-pack/functionbeat/manager/aws/op_delete_cloudformation.go deleted file mode 100644 index 4954e70b2666..000000000000 --- a/x-pack/functionbeat/manager/aws/op_delete_cloudformation.go +++ /dev/null @@ -1,63 +0,0 @@ -// Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one -// or more contributor license agreements. Licensed under the Elastic License; -// you may not use this file except in compliance with the Elastic License. - -package aws - -import ( - "context" - - "github.com/aws/aws-sdk-go-v2/aws" - "github.com/aws/aws-sdk-go-v2/service/cloudformation" - "github.com/gofrs/uuid/v5" - - "github.com/elastic/beats/v7/x-pack/functionbeat/manager/executor" - "github.com/elastic/elastic-agent-libs/logp" -) - -type opDeleteCloudFormation struct { - log *logp.Logger - svc deleteStackClient - stackName string -} - -func (o *opDeleteCloudFormation) Execute(ctx executor.Context) error { - c, ok := ctx.(*stackContext) - if !ok { - return errWrongContext - } - - uuid, err := uuid.NewV4() - if err != nil { - return err - } - - // retrieve the stack id from the name so we can have access to the Stack events when the - // stack is completely deleted. - stackID, err := queryStackID(o.svc, aws.String(o.stackName)) - if err != nil { - return err - } - c.ID = stackID - - input := &cloudformation.DeleteStackInput{ - ClientRequestToken: aws.String(uuid.String()), - StackName: aws.String(o.stackName), - } - - resp, err := o.svc.DeleteStack(context.TODO(), input) - if err != nil { - o.log.Debugf("Could not delete the stack, response: %v", resp) - return err - } - - return nil -} - -func newOpDeleteCloudFormation( - log *logp.Logger, - svc deleteStackClient, - stackName string, -) *opDeleteCloudFormation { - return &opDeleteCloudFormation{log: log, svc: svc, stackName: stackName} -} diff --git a/x-pack/functionbeat/manager/aws/op_delete_file_bucket.go b/x-pack/functionbeat/manager/aws/op_delete_file_bucket.go deleted file mode 100644 index e30664fde5be..000000000000 --- a/x-pack/functionbeat/manager/aws/op_delete_file_bucket.go +++ /dev/null @@ -1,52 +0,0 @@ -// Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one -// or more contributor license agreements. Licensed under the Elastic License; -// you may not use this file except in compliance with the Elastic License. - -package aws - -import ( - "context" - - "github.com/aws/aws-sdk-go-v2/aws" - "github.com/aws/aws-sdk-go-v2/service/s3" - - "github.com/elastic/beats/v7/x-pack/functionbeat/manager/executor" - "github.com/elastic/elastic-agent-libs/logp" -) - -type opDeleteFileBucket struct { - log *logp.Logger - svc *s3.Client - bucketName string - path string -} - -func newOpDeleteFileBucket( - log *logp.Logger, - config aws.Config, - bucketName, path string, -) *opDeleteFileBucket { - return &opDeleteFileBucket{ - log: log, - svc: s3.NewFromConfig(config), - bucketName: bucketName, - path: path, - } -} - -func (o *opDeleteFileBucket) Execute(_ executor.Context) error { - o.log.Debugf("Removing file '%s' on bucket '%s'", o.path, o.bucketName) - input := &s3.DeleteObjectInput{ - Bucket: aws.String(o.bucketName), - Key: aws.String(o.path), - } - - resp, err := o.svc.DeleteObject(context.TODO(), input) - - if err != nil { - o.log.Debugf("Could not remove object to S3, resp: %v", resp) - return err - } - o.log.Debug("Remove successful") - return nil -} diff --git a/x-pack/functionbeat/manager/aws/op_ensure_bucket.go b/x-pack/functionbeat/manager/aws/op_ensure_bucket.go deleted file mode 100644 index f394650c119c..000000000000 --- a/x-pack/functionbeat/manager/aws/op_ensure_bucket.go +++ /dev/null @@ -1,61 +0,0 @@ -// Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one -// or more contributor license agreements. Licensed under the Elastic License; -// you may not use this file except in compliance with the Elastic License. - -package aws - -import ( - "context" - "errors" - "fmt" - - "github.com/aws/smithy-go" - - "github.com/aws/aws-sdk-go-v2/aws" - "github.com/aws/aws-sdk-go-v2/service/s3" - - "github.com/elastic/beats/v7/x-pack/functionbeat/manager/executor" - "github.com/elastic/elastic-agent-libs/logp" -) - -// This error is not provided by the S3 error package. -const notFound = "NotFound" - -type opEnsureBucket struct { - log *logp.Logger - svc *s3.Client - bucketName string -} - -func newOpEnsureBucket(log *logp.Logger, cfg aws.Config, bucketName string) *opEnsureBucket { - return &opEnsureBucket{log: log, svc: s3.NewFromConfig(cfg), bucketName: bucketName} -} - -func (o *opEnsureBucket) Execute(_ executor.Context) error { - o.log.Debugf("Verifying presence of S3 bucket: %s", o.bucketName) - - check := &s3.HeadBucketInput{Bucket: aws.String(o.bucketName)} - _, err := o.svc.HeadBucket(context.TODO(), check) - if err == nil { - // The bucket exists and we have permission to access it. - return nil - } - - var apiError smithy.APIError - if errors.As(err, &apiError) { - if apiError.ErrorCode() == notFound { - // bucket do not exist let's create it. - input := &s3.CreateBucketInput{Bucket: aws.String(o.bucketName)} - resp, err := o.svc.CreateBucket(context.TODO(), input) - if err != nil { - o.log.Debugf("Could not create bucket, resp: %v", resp) - return err - } - // bucket created successfully - return nil - } - } - - // Catchall for unauthorized access. - return fmt.Errorf("bucket '%s' already exist and you don't have permission to access it: %w", o.bucketName, err) -} diff --git a/x-pack/functionbeat/manager/aws/op_update_cloudformation.go b/x-pack/functionbeat/manager/aws/op_update_cloudformation.go deleted file mode 100644 index 9a75909f2479..000000000000 --- a/x-pack/functionbeat/manager/aws/op_update_cloudformation.go +++ /dev/null @@ -1,68 +0,0 @@ -// Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one -// or more contributor license agreements. Licensed under the Elastic License; -// you may not use this file except in compliance with the Elastic License. - -package aws - -import ( - "context" - - "github.com/aws/aws-sdk-go-v2/service/cloudformation/types" - - "github.com/aws/aws-sdk-go-v2/aws" - "github.com/aws/aws-sdk-go-v2/service/cloudformation" - "github.com/gofrs/uuid/v5" - - "github.com/elastic/beats/v7/x-pack/functionbeat/manager/executor" - "github.com/elastic/elastic-agent-libs/logp" -) - -type opUpdateCloudFormation struct { - log *logp.Logger - svc updateStackClient - templateURL string - stackName string -} - -func (o *opUpdateCloudFormation) Execute(ctx executor.Context) error { - c, ok := ctx.(*stackContext) - if !ok { - return errWrongContext - } - - uuid, err := uuid.NewV4() - if err != nil { - return err - } - input := &cloudformation.UpdateStackInput{ - ClientRequestToken: aws.String(uuid.String()), - StackName: aws.String(o.stackName), - TemplateURL: aws.String(o.templateURL), - Capabilities: []types.Capability{ - types.CapabilityCapabilityNamedIam, - }, - } - - resp, err := o.svc.UpdateStack(context.TODO(), input) - if err != nil { - o.log.Debugf("Could not update the cloudformation stack, resp: %+v", resp) - return err - } - - c.ID = resp.StackId - - return nil -} - -func newOpUpdateCloudFormation( - log *logp.Logger, - svc updateStackClient, - templateURL, stackName string, -) *opUpdateCloudFormation { - return &opUpdateCloudFormation{ - log: log, - svc: svc, - templateURL: templateURL, - stackName: stackName, - } -} diff --git a/x-pack/functionbeat/manager/aws/op_upload_to_bucket.go b/x-pack/functionbeat/manager/aws/op_upload_to_bucket.go deleted file mode 100644 index 0825a26b35a8..000000000000 --- a/x-pack/functionbeat/manager/aws/op_upload_to_bucket.go +++ /dev/null @@ -1,68 +0,0 @@ -// Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one -// or more contributor license agreements. Licensed under the Elastic License; -// you may not use this file except in compliance with the Elastic License. - -package aws - -import ( - "bytes" - "context" - - "github.com/aws/aws-sdk-go-v2/aws" - "github.com/aws/aws-sdk-go-v2/service/s3" - - "github.com/elastic/beats/v7/x-pack/functionbeat/manager/executor" - "github.com/elastic/elastic-agent-libs/logp" -) - -type opUploadToBucket struct { - log *logp.Logger - svc *s3.Client - bucketName string - path string - raw []byte - config aws.Config -} - -func newOpUploadToBucket( - log *logp.Logger, - config aws.Config, - bucketName, path string, - raw []byte, -) *opUploadToBucket { - return &opUploadToBucket{ - log: log, - svc: s3.NewFromConfig(config), - bucketName: bucketName, - path: path, - raw: raw, - config: config, - } -} - -func (o *opUploadToBucket) Execute(_ executor.Context) error { - o.log.Debugf("Uploading file '%s' to bucket '%s' with size %d bytes", o.path, o.bucketName, len(o.raw)) - input := &s3.PutObjectInput{ - Bucket: aws.String(o.bucketName), - Body: bytes.NewReader(o.raw), - Key: aws.String(o.path), - } - resp, err := o.svc.PutObject(context.TODO(), input) - - if err != nil { - o.log.Debugf("Could not upload object to S3, resp: %v", resp) - return err - } - o.log.Debug("Upload successful") - return nil -} - -func (o *opUploadToBucket) Rollback(ctx executor.Context) error { - // The error will be logged but we do not enforce a hard failure because the file could have - // been removed before. - err := newOpDeleteFileBucket(o.log, o.config, o.bucketName, o.path).Execute(ctx) - if err != nil { - o.log.Debugf("Fail to delete file on bucket, error: %+v", err) - } - return nil -} diff --git a/x-pack/functionbeat/manager/aws/op_wait_cloud_formation.go b/x-pack/functionbeat/manager/aws/op_wait_cloud_formation.go deleted file mode 100644 index 7a800fc9773c..000000000000 --- a/x-pack/functionbeat/manager/aws/op_wait_cloud_formation.go +++ /dev/null @@ -1,145 +0,0 @@ -// Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one -// or more contributor license agreements. Licensed under the Elastic License; -// you may not use this file except in compliance with the Elastic License. - -package aws - -import ( - "context" - "errors" - "time" - - "github.com/aws/aws-sdk-go-v2/service/cloudformation/types" - - "github.com/aws/aws-sdk-go-v2/aws" - "github.com/aws/aws-sdk-go-v2/service/cloudformation" - - "github.com/elastic/beats/v7/x-pack/functionbeat/manager/executor" - "github.com/elastic/elastic-agent-libs/logp" -) - -var periodicCheck = 2 * time.Second - -type checkStatusFunc = func(status *types.StackStatus) (bool, error) - -type opWaitCloudFormation struct { - log *logp.Logger - svc *cloudformation.Client - checkStatus checkStatusFunc -} - -func newOpWaitCloudFormation( - log *logp.Logger, - svc *cloudformation.Client, -) *opWaitCloudFormation { - return &opWaitCloudFormation{ - log: log, - svc: svc, - checkStatus: checkCreateStatus, - } -} - -func newWaitDeleteCloudFormation( - log *logp.Logger, - cfg aws.Config, -) *opWaitCloudFormation { - return &opWaitCloudFormation{ - log: log, - svc: cloudformation.NewFromConfig(cfg), - checkStatus: checkDeleteStatus, - } -} - -func (o *opWaitCloudFormation) Execute(ctx executor.Context) error { - c, ok := ctx.(*stackContext) - if !ok { - return errWrongContext - } - - if c.ID == nil { - return errMissingStackID - } - - eventStackPoller := makeEventStackPoller(o.log, o.svc, periodicCheck, c) - eventStackPoller.Start() - defer eventStackPoller.Stop() - - for { - status, _, err := queryStackStatus(o.svc, c.ID) - if err != nil { - return err - } - - completed, err := o.checkStatus(status) - if err != nil { - return err - } - - if completed { - return nil - } - - <-time.After(periodicCheck) - } -} - -func checkCreateStatus(status *types.StackStatus) (bool, error) { - switch *status { - case types.StackStatusUpdateComplete: // OK - return true, nil - case types.StackStatusCreateComplete: // OK - return true, nil - case types.StackStatusRollbackFailed: - return true, errors.New("failed to create and rollback the stack") - case types.StackStatusRollbackComplete: - return true, errors.New("failed to create the stack") - } - return false, nil -} - -func checkDeleteStatus(status *types.StackStatus) (bool, error) { - switch *status { - case types.StackStatusDeleteComplete: // OK - return true, nil - case types.StackStatusDeleteFailed: - return true, errors.New("failed to delete the stack") - case types.StackStatusRollbackFailed: - return true, errors.New("failed to delete and rollback the stack") - case types.StackStatusRollbackComplete: - return true, errors.New("failed to delete the stack") - } - return false, nil -} - -func queryStack( - svc cloudformation.DescribeStacksAPIClient, - stackID *string, -) (*cloudformation.DescribeStacksOutput, error) { - input := &cloudformation.DescribeStacksInput{StackName: stackID} - resp, err := svc.DescribeStacks(context.TODO(), input) - if err != nil { - return nil, err - } - return resp, nil -} - -func queryStackStatus( - svc cloudformation.DescribeStacksAPIClient, - stackID *string, -) (*types.StackStatus, *string, error) { - resp, err := queryStack(svc, stackID) - if err != nil { - return nil, nil, err - } - - stack := resp.Stacks[0] - return &stack.StackStatus, stack.StackStatusReason, nil -} - -func queryStackID(svc cloudformation.DescribeStacksAPIClient, stackName *string) (*string, error) { - resp, err := queryStack(svc, stackName) - if err != nil { - return nil, err - } - return resp.Stacks[0].StackId, nil -} diff --git a/x-pack/functionbeat/manager/aws/policies_test.go b/x-pack/functionbeat/manager/aws/policies_test.go deleted file mode 100644 index 30b484d0b353..000000000000 --- a/x-pack/functionbeat/manager/aws/policies_test.go +++ /dev/null @@ -1,71 +0,0 @@ -// Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one -// or more contributor license agreements. Licensed under the Elastic License; -// you may not use this file except in compliance with the Elastic License. - -package aws - -import ( - "testing" - - "github.com/awslabs/goformation/v7/cloudformation" - "github.com/awslabs/goformation/v7/cloudformation/iam" - "github.com/stretchr/testify/assert" - - "github.com/elastic/beats/v7/x-pack/functionbeat/function/provider" - fnaws "github.com/elastic/beats/v7/x-pack/functionbeat/provider/aws/aws" - conf "github.com/elastic/elastic-agent-libs/config" -) - -func TestConfig(t *testing.T) { - t.Run("test permissions for event_source_arn", testPolicies) -} - -func testPolicies(t *testing.T) { - cfg := conf.MustNewConfigFrom(map[string]interface{}{ - "name": "myfunction", - "description": "mydescription", - "triggers": []map[string]interface{}{ - map[string]interface{}{ - "event_source_arn": "abc456", - }, - map[string]interface{}{ - "event_source_arn": "abc1234", - }, - }, - }) - - k, err := fnaws.NewKinesis(&provider.DefaultProvider{}, cfg) - if !assert.NoError(t, err) { - return - } - - i, ok := k.(installer) - if !assert.True(t, ok) { - return - } - - policies := i.Policies() - if !assert.Equal(t, 1, len(policies)) { - return - } - - // ensure permissions on specified resources - expected := iam.Role_Policy{ - PolicyName: cloudformation.Join("-", []string{"fnb", "kinesis", "myfunction"}), - PolicyDocument: map[string]interface{}{ - "Statement": []map[string]interface{}{ - map[string]interface{}{ - "Action": []string{ - "kinesis:GetRecords", - "kinesis:GetShardIterator", - "Kinesis:DescribeStream", - }, - "Effect": "Allow", - "Resource": []string{"abc1234", "abc456"}, - }, - }, - }, - } - - assert.Equal(t, expected, policies[0]) -} diff --git a/x-pack/functionbeat/manager/aws/stack_context.go b/x-pack/functionbeat/manager/aws/stack_context.go deleted file mode 100644 index 638422cb5bbd..000000000000 --- a/x-pack/functionbeat/manager/aws/stack_context.go +++ /dev/null @@ -1,24 +0,0 @@ -// Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one -// or more contributor license agreements. Licensed under the Elastic License; -// you may not use this file except in compliance with the Elastic License. - -package aws - -import ( - "errors" - "time" -) - -var ( - errWrongContext = errors.New("invalid type, expecting stack context") - errMissingStackID = errors.New("missing stack id") -) - -type stackContext struct { - ID *string - StartedAt time.Time -} - -func newStackContext() *stackContext { - return &stackContext{StartedAt: time.Now()} -} diff --git a/x-pack/functionbeat/manager/aws/template_builder.go b/x-pack/functionbeat/manager/aws/template_builder.go deleted file mode 100644 index d988f60d7088..000000000000 --- a/x-pack/functionbeat/manager/aws/template_builder.go +++ /dev/null @@ -1,331 +0,0 @@ -// Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one -// or more contributor license agreements. Licensed under the Elastic License; -// you may not use this file except in compliance with the Elastic License. - -package aws - -import ( - "crypto/sha256" - "encoding/base64" - "errors" - "fmt" - - "github.com/awslabs/goformation/v7/cloudformation" - "github.com/awslabs/goformation/v7/cloudformation/iam" - "github.com/awslabs/goformation/v7/cloudformation/lambda" - "github.com/awslabs/goformation/v7/cloudformation/logs" - "github.com/awslabs/goformation/v7/cloudformation/tags" - - "github.com/elastic/beats/v7/x-pack/functionbeat/function/provider" - "github.com/elastic/beats/v7/x-pack/functionbeat/manager/core" - "github.com/elastic/beats/v7/x-pack/functionbeat/manager/core/bundle" - fnaws "github.com/elastic/beats/v7/x-pack/functionbeat/provider/aws/aws" - conf "github.com/elastic/elastic-agent-libs/config" - "github.com/elastic/elastic-agent-libs/logp" -) - -// zipData stores the data on the zip to be deployed -type zipData struct { - content []byte - checksum string -} - -// templateData stores the template and its metadata required to deploy it -type templateData struct { - json []byte - checksum string - key string - url string - codeKey string - zip zipData -} - -type defaultTemplateBuilder struct { - provider provider.Provider - log *logp.Logger - endpoint string - bucket string -} - -const ( - keyPrefix = "functionbeat-deployment/" - - // Package size limits for AWS, we should be a lot under this limit but - // adding a check to make sure we never go over. - // Ref: https://docs.aws.amazon.com/lambda/latest/dg/limits.html - packageCompressedLimit = 50 * 1000 * 1000 // 50MB - packageUncompressedLimit = 250 * 1000 * 1000 // 250MB -) - -func NewTemplateBuilder(log *logp.Logger, cfg *conf.C, p provider.Provider) (provider.TemplateBuilder, error) { - config := &fnaws.Config{} - if err := cfg.Unpack(config); err != nil { - return nil, err - } - - return &defaultTemplateBuilder{ - provider: p, - log: log, - endpoint: config.Credentials.Endpoint, - bucket: string(config.DeployBucket), - }, nil -} - -func (d *defaultTemplateBuilder) findFunction(name string) (installer, error) { - fn, err := d.provider.FindFunctionByName(name) - if err != nil { - return nil, err - } - - function, ok := fn.(installer) - if !ok { - return nil, errors.New("incompatible type received, expecting: 'functionManager'") - } - - return function, nil -} - -// execute generates a template -func (d *defaultTemplateBuilder) execute(name string) (templateData, error) { - d.log.Debug("Compressing all assets into an artifact") - - content, err := core.MakeZip(packageUncompressedLimit, packageCompressedLimit, zipResources()) - if err != nil { - return templateData{}, err - } - d.log.Debugf("Compression is successful (zip size: %d bytes)", len(content)) - - function, err := d.findFunction(name) - if err != nil { - return templateData{}, err - } - - fnTemplate := function.Template() - - zipChecksum := checksum(content) - codeKey := keyPrefix + name + "/" + zipChecksum + "/functionbeat.zip" - to := d.template(function, name, codeKey) - if err := mergeTemplate(to, fnTemplate); err != nil { - return templateData{}, err - } - - templateJSON, err := to.JSON() - if err != nil { - return templateData{}, err - } - - templateChecksum := checksum(templateJSON) - templateKey := keyPrefix + name + "/" + templateChecksum + "/cloudformation-template-create.json" - templateURL := "https://" + d.bucket + "." + d.endpoint + "/" + templateKey - - return templateData{ - json: templateJSON, - checksum: templateChecksum, - key: templateKey, - url: templateURL, - codeKey: codeKey, - zip: zipData{ - checksum: zipChecksum, - content: content, - }, - }, nil -} - -func (d *defaultTemplateBuilder) template(function installer, name, codeLoc string) *cloudformation.Template { - lambdaConfig := function.LambdaConfig() - - prefix := func(s string) string { - return fnaws.NormalizeResourceName("fnb" + name + s) - } - - // AWS variables references:. - // AWS::Partition: aws, aws-cn, aws-gov. - // AWS::Region: us-east-1, us-east-2, ap-northeast-3, - // AWS::AccountId: account id for the current request. - // AWS::URLSuffix: amazonaws.com - // - // Documentation: https://docs.aws.amazon.com/AWSCloudFormation/latest/APIReference/Welcome.html - // Intrinsic function reference: https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/intrinsic-function-reference.html - - template := cloudformation.NewTemplate() - - role := lambdaConfig.Role - dependsOn := make([]string, 0) - if lambdaConfig.Role == "" { - d.log.Infof("No role is configured for function %s, creating a custom role.", name) - - roleRes := prefix("") + "IAMRoleLambdaExecution" - template.Resources[roleRes] = d.roleTemplate(function, name) - role = cloudformation.GetAtt(roleRes, "Arn") - dependsOn = []string{roleRes} - } - - // Configure the Dead letter, any failed events will be send to the configured amazon resource name. - var dlc *lambda.Function_DeadLetterConfig - if lambdaConfig.DeadLetterConfig != nil && len(lambdaConfig.DeadLetterConfig.TargetArn) != 0 { - dlc = &lambda.Function_DeadLetterConfig{ - TargetArn: cloudformation.String(lambdaConfig.DeadLetterConfig.TargetArn), - } - } - - // Configure VPC - var vcpConf *lambda.Function_VpcConfig - if lambdaConfig.VPCConfig != nil && len(lambdaConfig.VPCConfig.SecurityGroupIDs) != 0 && len(lambdaConfig.VPCConfig.SubnetIDs) != 0 { - vcpConf = &lambda.Function_VpcConfig{ - SecurityGroupIds: lambdaConfig.VPCConfig.SecurityGroupIDs, - SubnetIds: lambdaConfig.VPCConfig.SubnetIDs, - } - } - - ts := make([]tags.Tag, 0, len(lambdaConfig.Tags)) - for name, val := range lambdaConfig.Tags { - tag := tags.Tag{ - Key: name, - Value: val, - } - ts = append(ts, tag) - } - - // Create the lambda - // Doc: https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-lambda-function.html - template.Resources[prefix("")] = &AWSLambdaFunction{ - Function: &lambda.Function{ - Code: &lambda.Function_Code{ - S3Bucket: cloudformation.String(d.bucket), - S3Key: cloudformation.String(codeLoc), - }, - Description: cloudformation.String(lambdaConfig.Description), - Environment: &lambda.Function_Environment{ - // Configure which function need to be run by the lambda function. - Variables: map[string]string{ - "BEAT_STRICT_PERMS": "false", // Disable any check on disk, we are running with really differents permission on lambda. - "ENABLED_FUNCTIONS": name, - }, - }, - DeadLetterConfig: dlc, - VpcConfig: vcpConf, - FunctionName: cloudformation.String(name), - Role: role, - Runtime: cloudformation.String(runtime), - Handler: cloudformation.String(handlerName), - MemorySize: cloudformation.Int(lambdaConfig.MemorySize.Megabytes()), - ReservedConcurrentExecutions: cloudformation.Int(lambdaConfig.Concurrency), - Timeout: cloudformation.Int(int(lambdaConfig.Timeout.Seconds())), - Tags: ts, - }, - DependsOn: dependsOn, - } - - // Create the log group for the specific function lambda. - template.Resources[prefix("LogGroup")] = &logs.LogGroup{ - LogGroupName: cloudformation.String("/aws/lambda/" + name), - } - - return template -} - -func (d *defaultTemplateBuilder) roleTemplate(function installer, name string) *iam.Role { - // Default policies to writes logs from the Lambda. - policies := []iam.Role_Policy{ - iam.Role_Policy{ - PolicyName: cloudformation.Join("-", []string{"fnb", "lambda", name}), - PolicyDocument: map[string]interface{}{ - "Statement": []map[string]interface{}{ - map[string]interface{}{ - "Action": []string{"logs:CreateLogStream", "logs:PutLogEvents"}, - "Effect": "Allow", - "Resource": []string{ - cloudformation.Sub("arn:${AWS::Partition}:logs:${AWS::Region}:${AWS::AccountId}:log-group:/aws/lambda/" + name + ":*"), - }, - }, - }, - }, - }, - } - - // Merge any specific policies from the service. - policies = append(policies, function.Policies()...) - - // Create the roles for the lambda. - // doc: https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-iam-role.html - return &iam.Role{ - AssumeRolePolicyDocument: map[string]interface{}{ - "Statement": []interface{}{ - map[string]interface{}{ - "Action": "sts:AssumeRole", - "Effect": "Allow", - "Principal": map[string]interface{}{ - "Service": cloudformation.Join("", []string{ - "lambda.", - cloudformation.Ref("AWS::URLSuffix"), - }), - }, - }, - }, - }, - Path: cloudformation.String("/"), - RoleName: cloudformation.String("functionbeat-lambda-" + name + "-" + cloudformation.Ref("AWS::Region")), - // Allow the lambda to write log to cloudwatch logs. - // doc: https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-iam-policy.html - Policies: policies, - } -} - -// RawTemplate generates a template and returns it in a string -func (d *defaultTemplateBuilder) RawTemplate(name string) (string, error) { - data, err := d.execute(name) - return string(data.json), err -} - -func merge[M1 ~map[K]V, M2 ~map[K]V, K comparable, V any](m1 M1, m2 M2) error { - for k, v := range m2 { - if _, ok := m1[k]; ok { - return fmt.Errorf("key %v already exist in the template map", k) - } - m1[k] = v - } - return nil -} - -// mergeTemplate takes two cloudformation and merge them, if a key already exist we return an error. -func mergeTemplate(to, from *cloudformation.Template) error { - err := merge(to.Parameters, from.Parameters) - if err != nil { - return err - } - - err = merge(to.Mappings, from.Mappings) - if err != nil { - return err - } - - err = merge(to.Conditions, from.Conditions) - if err != nil { - return err - } - - for k, v := range from.Resources { - if _, ok := to.Resources[k]; ok { - return fmt.Errorf("key %s already exist in the template map", k) - } - to.Resources[k] = v - } - - err = merge(to.Outputs, from.Outputs) - if err != nil { - return err - } - - return nil -} - -func checksum(data []byte) string { - sha := sha256.Sum256(data) - return base64.RawURLEncoding.EncodeToString(sha[:]) -} - -func zipResources() []bundle.Resource { - return []bundle.Resource{ - &bundle.LocalFile{Path: "pkg/functionbeat-aws", FileMode: 0755}, - } -} diff --git a/x-pack/functionbeat/manager/beater/functionbeat.go b/x-pack/functionbeat/manager/beater/functionbeat.go deleted file mode 100644 index b8e702860d03..000000000000 --- a/x-pack/functionbeat/manager/beater/functionbeat.go +++ /dev/null @@ -1,58 +0,0 @@ -// Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one -// or more contributor license agreements. Licensed under the Elastic License; -// you may not use this file except in compliance with the Elastic License. - -package beater - -import ( - "fmt" - "time" - - "github.com/elastic/beats/v7/libbeat/beat" - "github.com/elastic/beats/v7/x-pack/functionbeat/config" - conf "github.com/elastic/elastic-agent-libs/config" - "github.com/elastic/elastic-agent-libs/logp" -) - -var ( - graceDelay = 45 * time.Minute - refreshDelay = 15 * time.Minute -) - -// Functionbeat is a beat designed to run under a serverless environment and listen to external triggers, -// each invocation will generate one or more events to Elasticsearch. -// -// Each serverless implementation is different but functionbeat follows a few execution rules. -// - Publishing events from the source to the output is done synchronously. -// - Execution can be suspended. -// - Run on a read only filesystem -// - More execution constraints based on speed and memory usage. -type Functionbeat struct { - log *logp.Logger - Config *config.Config -} - -// New creates an instance of functionbeat. -func New(b *beat.Beat, cfg *conf.C) (beat.Beater, error) { - c := &config.DefaultConfig - if err := cfg.Unpack(c); err != nil { - return nil, fmt.Errorf("error reading config file: %+v", err) - } - - bt := &Functionbeat{ - log: logp.NewLogger("functionbeat"), - Config: c, - } - return bt, nil -} - -// Run starts functionbeat. -func (bt *Functionbeat) Run(b *beat.Beat) error { - bt.log.Info("Functionbeat is running") - defer bt.log.Info("Functionbeat stopped running") - - return nil -} - -// Stop stops Functionbeat. -func (bt *Functionbeat) Stop() {} diff --git a/x-pack/functionbeat/manager/cmd/cli_handler.go b/x-pack/functionbeat/manager/cmd/cli_handler.go deleted file mode 100644 index 473f6b038f0e..000000000000 --- a/x-pack/functionbeat/manager/cmd/cli_handler.go +++ /dev/null @@ -1,162 +0,0 @@ -// Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one -// or more contributor license agreements. Licensed under the Elastic License; -// you may not use this file except in compliance with the Elastic License. - -package cmd - -import ( - "errors" - "fmt" - "io" - "strings" - - "github.com/elastic/beats/v7/x-pack/functionbeat/function/provider" - "github.com/elastic/elastic-agent-libs/logp" -) - -// Errors generated by the cliHandler. -var ( - errNoFunctionGiven = errors.New("no function given") -) - -// cliHandler takes a provider.CLIManager and acts a bridge between user enterred content from the CLI -// and the type managing the function on the provider. It allow to specify multiple functions at -// the command line but will do a single invocation on the CLIManager and will do general validation -// and normalization of the values. It also communicate the status of the operations to the user. -// -// NOTES: Each execution call of the CLIManager are independant, this mean that a fail call will not -// stop other calls to succeed. -// -// TODO(ph) functions could be merged into a single call , but I thought it was premature to do -// it. -type cliHandler struct { - clis map[string]provider.CLIManager - log *logp.Logger - errOutput io.Writer - output io.Writer - - functionsByProvider map[string]string -} - -func newCLIHandler(clis map[string]provider.CLIManager, functionsByProvider map[string]string, errOutput io.Writer, output io.Writer) *cliHandler { - return &cliHandler{ - clis: clis, - errOutput: errOutput, - functionsByProvider: functionsByProvider, - output: output, - log: logp.NewLogger("cli-handler"), - } -} - -func (c *cliHandler) Deploy(names []string) error { - c.log.Debugf("Starting deploy for: %s", strings.Join(names, ", ")) - defer c.log.Debug("Deploy execution ended") - - if len(names) == 0 { - return errNoFunctionGiven - } - - errCount := c.iterateCLIFuncVerbose(names, "deploy", provider.CLIManager.Deploy) - - if errCount > 0 { - return fmt.Errorf("Fail to deploy %d function(s)", errCount) - } - return nil -} - -func (c *cliHandler) Update(names []string) error { - c.log.Debugf("Starting update for: %s", strings.Join(names, ", ")) - defer c.log.Debug("Update execution ended") - - if len(names) == 0 { - return errNoFunctionGiven - } - - errCount := c.iterateCLIFuncVerbose(names, "update", provider.CLIManager.Update) - - if errCount > 0 { - return fmt.Errorf("fail to update %d function(s)", errCount) - } - return nil -} - -func (c *cliHandler) Remove(names []string) error { - c.log.Debugf("Starting remove for: %s", strings.Join(names, ", ")) - defer c.log.Debug("Remove execution ended") - - if len(names) == 0 { - return errNoFunctionGiven - } - - errCount := c.iterateCLIFuncVerbose(names, "remove", provider.CLIManager.Remove) - - if errCount > 0 { - return fmt.Errorf("fail to remove %d function(s)", errCount) - } - return nil -} - -func (c *cliHandler) Export(names []string) error { - c.log.Debugf("Starting export for: %s", strings.Join(names, ", ")) - defer c.log.Debug("Export execution ended") - - if len(names) == 0 { - return errNoFunctionGiven - } - - errCount := c.iterateCLIFuncQuiet(names, "export", provider.CLIManager.Export) - - if errCount > 0 { - return fmt.Errorf("fail to export %d function(s)", errCount) - } - return nil -} - -func (c *cliHandler) Package(outputPattern string) error { - for _, cli := range c.clis { - err := cli.Package(outputPattern) - if err != nil { - return err - } - } - return nil -} - -func (c *cliHandler) iterateCLIFuncVerbose(names []string, operation string, f func(provider.CLIManager, string) error) int { - return c.iterateCLIFunc(names, operation, f, true) -} - -func (c *cliHandler) iterateCLIFuncQuiet(names []string, operation string, f func(provider.CLIManager, string) error) int { - return c.iterateCLIFunc(names, operation, f, false) -} - -func (c *cliHandler) iterateCLIFunc(names []string, operation string, f func(provider.CLIManager, string) error, verbose bool) int { - errCount := 0 - for _, name := range names { - providerName, ok := c.functionsByProvider[name] - if !ok { - fmt.Fprintf(c.errOutput, "Function: %s, could not be %sed. Enable it.\n", name, operation) - errCount++ - continue - } - - cli, ok := c.clis[providerName] - if !ok { - fmt.Fprintf(c.errOutput, "Function: %s, could not be %s. Selected provider '%s' cannot be found", name, operation, providerName) - errCount++ - continue - } - - err := f(cli, name) - if err != nil { - fmt.Fprintf(c.errOutput, "Function: %s, could not %s, error: %s\n", name, operation, err) - errCount++ - continue - } - - if verbose { - fmt.Fprintf(c.output, "Function: %s, %s successful\n", name, operation) - } - } - return errCount -} diff --git a/x-pack/functionbeat/manager/cmd/cli_handler_test.go b/x-pack/functionbeat/manager/cmd/cli_handler_test.go deleted file mode 100644 index 726ee93e9a1c..000000000000 --- a/x-pack/functionbeat/manager/cmd/cli_handler_test.go +++ /dev/null @@ -1,161 +0,0 @@ -// Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one -// or more contributor license agreements. Licensed under the Elastic License; -// you may not use this file except in compliance with the Elastic License. - -package cmd - -import ( - "bytes" - "errors" - "io" - "testing" - - "github.com/stretchr/testify/assert" - "github.com/stretchr/testify/mock" - - "github.com/elastic/beats/v7/x-pack/functionbeat/function/provider" -) - -type mockCLIManager struct { - mock.Mock -} - -func (m *mockCLIManager) Deploy(name string) error { - args := m.Called(name) - return args.Error(0) -} - -func (m *mockCLIManager) Update(name string) error { - args := m.Called(name) - return args.Error(0) -} - -func (m *mockCLIManager) Remove(name string) error { - args := m.Called(name) - return args.Error(0) -} - -func (m *mockCLIManager) Export(name string) error { - args := m.Called(name) - return args.Error(0) -} - -func (m *mockCLIManager) Package(outputPattern string) error { - args := m.Called(outputPattern) - return args.Error(0) -} - -func outputs() (io.Writer, io.Writer) { - errOut := new(bytes.Buffer) - output := new(bytes.Buffer) - return errOut, output -} - -func functionByProvider() map[string]string { - return map[string]string{ - "super": "mockProvider", - "saiyajin": "mockProvider", - } -} - -func wrapCLIManager(m provider.CLIManager) map[string]provider.CLIManager { - return map[string]provider.CLIManager{ - "mockProvider": m, - } -} - -func TestCliHandler(t *testing.T) { - t.Run("deploy", testDeploy) - t.Run("update", testUpdate) - t.Run("remove", testRemove) -} - -func testDeploy(t *testing.T) { - t.Run("return error when no functions are specified", func(t *testing.T) { - errOut, output := outputs() - handler := newCLIHandler(wrapCLIManager(&mockCLIManager{}), functionByProvider(), errOut, output) - err := handler.Deploy([]string{}) - assert.Equal(t, errNoFunctionGiven, err) - }) - - t.Run("return an error if the manager return an error", func(t *testing.T) { - errOut, output := outputs() - myErr := errors.New("my error") - m := &mockCLIManager{} - m.On("Deploy", "saiyajin").Return(myErr) - handler := newCLIHandler(wrapCLIManager(m), functionByProvider(), errOut, output) - err := handler.Deploy([]string{"saiyajin"}) - assert.Error(t, err) - }) - - t.Run("call the method for all the functions", func(t *testing.T) { - errOut, output := outputs() - m := &mockCLIManager{} - m.On("Deploy", "super").Return(nil) - m.On("Deploy", "saiyajin").Return(nil) - handler := newCLIHandler(wrapCLIManager(m), functionByProvider(), errOut, output) - err := handler.Deploy([]string{"super", "saiyajin"}) - assert.NoError(t, err) - m.AssertExpectations(t) - }) -} - -func testUpdate(t *testing.T) { - t.Run("return error when no functions are specified", func(t *testing.T) { - errOut, output := outputs() - handler := newCLIHandler(wrapCLIManager(&mockCLIManager{}), functionByProvider(), errOut, output) - err := handler.Update([]string{}) - assert.Equal(t, errNoFunctionGiven, err) - }) - - t.Run("return an error if the manager return an error", func(t *testing.T) { - errOut, output := outputs() - myErr := errors.New("my error") - m := &mockCLIManager{} - m.On("Update", "saiyajin").Return(myErr) - handler := newCLIHandler(wrapCLIManager(m), functionByProvider(), errOut, output) - err := handler.Update([]string{"saiyajin"}) - assert.Error(t, err) - }) - - t.Run("call the method for all the functions", func(t *testing.T) { - errOut, output := outputs() - m := &mockCLIManager{} - m.On("Update", "super").Return(nil) - m.On("Update", "saiyajin").Return(nil) - handler := newCLIHandler(wrapCLIManager(m), functionByProvider(), errOut, output) - err := handler.Update([]string{"super", "saiyajin"}) - assert.NoError(t, err) - m.AssertExpectations(t) - }) -} - -func testRemove(t *testing.T) { - t.Run("return error when no functions are specified", func(t *testing.T) { - errOut, output := outputs() - handler := newCLIHandler(wrapCLIManager(&mockCLIManager{}), functionByProvider(), errOut, output) - err := handler.Remove([]string{}) - assert.Equal(t, errNoFunctionGiven, err) - }) - - t.Run("return an error if the manager return an error", func(t *testing.T) { - errOut, output := outputs() - myErr := errors.New("my error") - m := &mockCLIManager{} - m.On("Remove", "saiyajin").Return(myErr) - handler := newCLIHandler(wrapCLIManager(m), functionByProvider(), errOut, output) - err := handler.Remove([]string{"saiyajin"}) - assert.Error(t, err) - }) - - t.Run("call the method for all the functions", func(t *testing.T) { - errOut, output := outputs() - m := &mockCLIManager{} - m.On("Remove", "super").Return(nil) - m.On("Remove", "saiyajin").Return(nil) - handler := newCLIHandler(wrapCLIManager(m), functionByProvider(), errOut, output) - err := handler.Remove([]string{"super", "saiyajin"}) - assert.NoError(t, err) - m.AssertExpectations(t) - }) -} diff --git a/x-pack/functionbeat/manager/cmd/provider_cmd.go b/x-pack/functionbeat/manager/cmd/provider_cmd.go deleted file mode 100644 index 70c0637f108c..000000000000 --- a/x-pack/functionbeat/manager/cmd/provider_cmd.go +++ /dev/null @@ -1,142 +0,0 @@ -// Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one -// or more contributor license agreements. Licensed under the Elastic License; -// you may not use this file except in compliance with the Elastic License. - -package cmd - -import ( - "os" - "path/filepath" - - "github.com/spf13/cobra" - - "github.com/elastic/beats/v7/libbeat/cmd/instance" - "github.com/elastic/beats/v7/libbeat/common/cli" - "github.com/elastic/beats/v7/x-pack/functionbeat/config" - "github.com/elastic/beats/v7/x-pack/functionbeat/function/provider" -) - -func initProviders() ([]provider.Provider, error) { - b, err := instance.NewInitializedBeat(instance.Settings{ - Name: Name, - ConfigOverrides: config.Overrides, - }) - if err != nil { - return nil, err - } - - c, err := b.BeatConfig() - if err != nil { - return nil, err - } - - cfg := &config.DefaultConfig - if err := c.Unpack(cfg); err != nil { - return nil, err - } - - var providers []provider.Provider - for _, p := range cfg.Provider.GetFields() { - isAvailable, err := provider.IsAvailable(p) - if err != nil { - return nil, err - } - if !isAvailable { - continue - } - - providerCfg, err := cfg.Provider.Child(p, -1) - if err != nil { - return nil, err - } - provider, err := provider.NewProvider(p, providerCfg) - if err != nil { - return nil, err - } - providers = append(providers, provider) - } - - return providers, nil -} - -func handler() (*cliHandler, error) { - providers, err := initProviders() - if err != nil { - return nil, err - } - - clis := make(map[string]provider.CLIManager) - functionsByProvider := make(map[string]string) - for _, provider := range providers { - cli, err := provider.CLIManager() - if err != nil { - return nil, err - } - clis[provider.Name()] = cli - - enabledFunctions, err := provider.EnabledFunctions() - if err != nil { - return nil, err - } - - for _, f := range enabledFunctions { - functionsByProvider[f] = provider.Name() - } - } - return newCLIHandler(clis, functionsByProvider, os.Stdout, os.Stderr), nil -} - -func genCLICmd(use, short string, fn func(*cliHandler, []string) error) *cobra.Command { - return &cobra.Command{ - Use: use, - Short: short, - Run: cli.RunWith(func(_ *cobra.Command, args []string) error { - h, err := handler() - if err != nil { - return err - } - - return fn(h, args) - }), - } -} - -func genDeployCmd() *cobra.Command { - return genCLICmd("deploy", "Deploy a function", (*cliHandler).Deploy) -} - -func genUpdateCmd() *cobra.Command { - return genCLICmd("update", "Update a function", (*cliHandler).Update) -} - -func genRemoveCmd() *cobra.Command { - return genCLICmd("remove", "Remove a function", (*cliHandler).Remove) -} - -func genExportFunctionCmd() *cobra.Command { - return genCLICmd("function", "Export function template", (*cliHandler).Export) -} - -func genPackageCmd() *cobra.Command { - var outputPattern string - cmd := &cobra.Command{ - Use: "package", - Short: "Package the configuration and the executable in a zip", - Run: cli.RunWith(func(cmd *cobra.Command, args []string) error { - h, err := handler() - if err != nil { - return err - } - return h.Package(outputPattern) - }), - } - - dir, err := os.Getwd() - if err != nil { - panic(err) - } - - defaultOutput := filepath.Join(dir, "package-{{.Provider}}.zip") - cmd.Flags().StringVarP(&outputPattern, "output", "o", defaultOutput, "full path pattern to the package") - return cmd -} diff --git a/x-pack/functionbeat/manager/cmd/root.go b/x-pack/functionbeat/manager/cmd/root.go deleted file mode 100644 index fb44d45e3316..000000000000 --- a/x-pack/functionbeat/manager/cmd/root.go +++ /dev/null @@ -1,50 +0,0 @@ -// Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one -// or more contributor license agreements. Licensed under the Elastic License; -// you may not use this file except in compliance with the Elastic License. - -package cmd - -import ( - "os" - - "github.com/spf13/cobra" - - cmd "github.com/elastic/beats/v7/libbeat/cmd" - "github.com/elastic/beats/v7/libbeat/cmd/instance" - "github.com/elastic/beats/v7/x-pack/functionbeat/config" - "github.com/elastic/beats/v7/x-pack/functionbeat/manager/beater" -) - -// Name of this beat -var Name = "functionbeat" - -// RootCmd to handle functionbeat -var RootCmd *cmd.BeatsRootCmd - -func init() { - RootCmd = cmd.GenRootCmdWithSettings(beater.New, instance.Settings{ - Name: Name, - HasDashboards: false, - ConfigOverrides: config.Overrides, - ElasticLicensed: true, - }) - - RootCmd.RemoveCommand(RootCmd.RunCmd) - RootCmd.Run = func(_ *cobra.Command, _ []string) { - - RootCmd.Usage() - os.Exit(1) - } - - RootCmd.AddCommand(genDeployCmd()) - RootCmd.AddCommand(genUpdateCmd()) - RootCmd.AddCommand(genRemoveCmd()) - RootCmd.AddCommand(genPackageCmd()) - - addBeatSpecificSubcommands() -} - -func addBeatSpecificSubcommands() { - RootCmd.ExportCmd.Short = "Export current config, index template or function" - RootCmd.ExportCmd.AddCommand(genExportFunctionCmd()) -} diff --git a/x-pack/functionbeat/manager/core/bundle/bundle.go b/x-pack/functionbeat/manager/core/bundle/bundle.go deleted file mode 100644 index f034c4400f49..000000000000 --- a/x-pack/functionbeat/manager/core/bundle/bundle.go +++ /dev/null @@ -1,243 +0,0 @@ -// Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one -// or more contributor license agreements. Licensed under the Elastic License; -// you may not use this file except in compliance with the Elastic License. - -package bundle - -import ( - "archive/zip" - "bufio" - "bytes" - "fmt" - "io" - "io/ioutil" - "os" - "path/filepath" -) - -// ReadCloserWith takes a reader and a closer for the specific reader and return an io.ReaderCloser. -func ReadCloserWith(reader io.Reader, closer io.Closer) io.ReadCloser { - return &ReadCloser{reader: reader, closer: closer} -} - -// ReadCloser wraps a io.Reader and a file handle into a FileReadCloser interface, -// this leave the responsability on the consumer to close the handle when its done consuming the -// io.Reader. -type ReadCloser struct { - reader io.Reader - closer io.Closer -} - -// Read proxies the Read to the original io.Reader. -func (f *ReadCloser) Read(p []byte) (int, error) { - return f.reader.Read(p) -} - -// Close closes the file handle this must be called after consuming the io.Reader to make sure we -// don't leak any file handle. -func (f *ReadCloser) Close() error { - return f.closer.Close() -} - -// Resource is the interface used to bundle the resource, a resource can be a local or a remote file. -// Reader must be a io.ReadCloser, this make it easier to deal with streaming of remote data. -type Resource interface { - // Open return an io.ReadCloser of the original resource, this will be used to stream content to - // The compressed file. - Open() (io.ReadCloser, error) - - // Name return the string that will be used as the file name inside the Zip file. - Name() string - - // Mode returns the permission of the file. - Mode() os.FileMode -} - -// Folder returns a list of files in a folder. -func Folder(folder, root string, filemode os.FileMode) []Resource { - resources := make([]Resource, 0) - err := filepath.Walk(folder, func(path string, info os.FileInfo, err error) error { - if err != nil { - return err - } - - if info.IsDir() { - return nil - } - - resources = append(resources, &RelativeFile{LocalFile{Path: path, FileMode: filemode}, root}) - - return nil - }) - - if err != nil { - return nil - } - - return resources -} - -// LocalFile represents a local file on disk. -type LocalFile struct { - Path string - FileMode os.FileMode -} - -// Open return a reader for the opened file. -func (l *LocalFile) Open() (io.ReadCloser, error) { - fd, err := os.Open(l.Path) - if err != nil { - return nil, err - } - - reader := bufio.NewReader(fd) - return ReadCloserWith(reader, fd), nil -} - -// Name return the basename of the file to be used as the name of the file in the archive. -func (l *LocalFile) Name() string { - return filepath.Base(l.Path) -} - -// Mode return the permissions of the file in the zip. -func (l *LocalFile) Mode() os.FileMode { - return l.FileMode -} - -// RelativeFile is a Localfile which needs to be placed relatively in the -// root of the bundle. -type RelativeFile struct { - LocalFile - root string -} - -// Name returns the name of the file. -func (r *RelativeFile) Name() string { - if r.root == "" { - return r.LocalFile.Path - } - return r.LocalFile.Path[len(r.root)+1:] -} - -// MemoryFile an in-memory representation of a physical file. -type MemoryFile struct { - Path string - FileMode os.FileMode - Raw []byte -} - -// Open the reader for the raw byte slice. -func (m *MemoryFile) Open() (io.ReadCloser, error) { - reader := bytes.NewReader(m.Raw) - return ioutil.NopCloser(reader), nil -} - -// Name returns the path to use in the zip. -func (m *MemoryFile) Name() string { - return m.Path -} - -// Mode returns the permission of the file. -func (m *MemoryFile) Mode() os.FileMode { - return m.FileMode -} - -// ZipBundle accepts a set of local files to bundle them into a zip file, it also accept size limits -// for the uncompressed and the compressed data. -type ZipBundle struct { - resources []Resource - maxSizeUncompressed int64 - maxSizeCompressed int64 -} - -// NewZipWithoutLimits creates a bundle that doesn't impose any limit on the uncompressed data and the -// compressed data. -func NewZipWithoutLimits(resources ...Resource) *ZipBundle { - return NewZipWithLimits(-1, -1, resources...) -} - -// NewZipWithLimits creates a Bundle that impose limit for the uncompressed data and the compressed data, -// using a limit of -1 with desactivate the check. -func NewZipWithLimits(maxSizeUncompressed, maxSizeCompressed int64, resources ...Resource) *ZipBundle { - return &ZipBundle{ - resources: resources, - maxSizeUncompressed: maxSizeUncompressed, - maxSizeCompressed: maxSizeCompressed, - } -} - -// Bytes takes the resources and bundle them into a zip and validates if needed that the -// created resources doesn't go over any predefined size limits. -func (p *ZipBundle) Bytes() ([]byte, error) { - buf := new(bytes.Buffer) - zipWriter := zip.NewWriter(buf) - - var uncompressed int64 - for _, file := range p.resources { - l, err := zipAddFile(zipWriter, file) - if err != nil { - return nil, err - } - - uncompressed = uncompressed + l - if p.maxSizeUncompressed != -1 && uncompressed > p.maxSizeUncompressed { - // Close the current zip, the zip has incomplete data. - zipWriter.Close() - return nil, fmt.Errorf( - "max uncompressed size reached, size %d, limit is %d", - uncompressed, - p.maxSizeUncompressed, - ) - } - - if l == 0 { - continue - } - - // Force a flush to accurately check for the size of the bytes.Buffer and see if - // we are over the limit. - if err := zipWriter.Flush(); err != nil { - return nil, err - } - - if p.maxSizeCompressed != -1 && int64(buf.Len()) > p.maxSizeCompressed { - // Close the current zip, the zip has incomplete data. - zipWriter.Close() - return nil, fmt.Errorf( - "max compressed size reached, size %d, limit is %d", - buf.Len(), - p.maxSizeCompressed, - ) - } - } - - // Flush bytes/writes headers, the zip is valid at this point. - zipWriter.Close() - return buf.Bytes(), nil -} - -func zipAddFile(zipWriter *zip.Writer, r Resource) (int64, error) { - f, err := r.Open() - if err != nil { - return 0, err - } - defer f.Close() - - header := &zip.FileHeader{ - Name: r.Name(), - Method: zip.Deflate, - } - - header.SetMode(r.Mode()) - w, err := zipWriter.CreateHeader(header) - if err != nil { - return 0, err - } - - l, err := io.Copy(w, f) - if err != nil { - return 0, err - } - - return l, nil -} diff --git a/x-pack/functionbeat/manager/core/bundle/bundle_test.go b/x-pack/functionbeat/manager/core/bundle/bundle_test.go deleted file mode 100644 index 89d010522b77..000000000000 --- a/x-pack/functionbeat/manager/core/bundle/bundle_test.go +++ /dev/null @@ -1,150 +0,0 @@ -// Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one -// or more contributor license agreements. Licensed under the Elastic License; -// you may not use this file except in compliance with the Elastic License. - -package bundle - -import ( - "archive/zip" - "bytes" - "io/ioutil" - "os" - "testing" - - "github.com/stretchr/testify/assert" - - "github.com/elastic/beats/v7/libbeat/common" -) - -func newFixedResource(name string, length int64) *MemoryFile { - paddingData, err := common.RandomBytes(int(length)) - if err != nil { - // fatal, This mean something is wrong with the random number generator. - panic(err) - } - return &MemoryFile{Path: name, Raw: paddingData, FileMode: 0755} -} - -func TestZipBundle(t *testing.T) { - t.Run("with limits", testWithLimits) - t.Run("with no limits", testArtifact(-1, -1)) -} - -func testWithLimits(t *testing.T) { - t.Run("uncompressed size is over limit", func(t *testing.T) { - limit := int64(50) - bundle := NewZipWithLimits(limit, -1, newFixedResource("ok.yml", limit+1)) - _, err := bundle.Bytes() - assert.Error(t, err) - }) - - t.Run("compressed size is over limit", func(t *testing.T) { - limit := int64(10) - bundle := NewZipWithLimits(-1, limit, newFixedResource("ok.yml", 2*limit)) - _, err := bundle.Bytes() - assert.Error(t, err) - }) - - t.Run("zip artifact is under limit and valid", testArtifact(1000, 1000)) -} - -func testArtifact(maxSizeUncompressed, maxSizeCompressed int64) func(t *testing.T) { - return func(t *testing.T) { - m := map[string]*MemoryFile{ - "f1.txt": newFixedResource("f1.txt", 65), - "f2.txt": newFixedResource("f2.txt", 100), - } - - resources := make([]Resource, len(m)) - var idx int - for _, r := range m { - resources[idx] = r - idx++ - } - - bundle := NewZipWithLimits(maxSizeUncompressed, maxSizeCompressed, resources...) - b, err := bundle.Bytes() - if !assert.NoError(t, err) { - return - } - - zip, err := zip.NewReader(bytes.NewReader(b), int64(len(b))) - if !assert.NoError(t, err) { - return - } - - if !assert.Equal(t, 2, len(zip.File)) { - return - } - - for _, file := range zip.File { - r, ok := m[file.Name] - if !assert.True(t, ok) { - t.Fatal("unknown file present in the zip") - } - - reader, err := file.Open() - if !assert.NoError(t, err) { - return - } - defer reader.Close() - - raw, err := ioutil.ReadAll(reader) - if !assert.NoError(t, err) { - return - } - - assert.True(t, bytes.Equal(r.Raw, raw), "bytes doesn't match") - } - } -} - -func TestLocalFile(t *testing.T) { - local := LocalFile{Path: "testdata/lipsum.txt", FileMode: 755} - - assert.Equal(t, "lipsum.txt", local.Name()) - assert.Equal(t, os.FileMode(755), local.Mode()) - - reader, err := local.Open() - if !assert.NoError(t, err) { - return - } - - defer func() { - err := reader.Close() - assert.NoError(t, err) - }() - - content, err := ioutil.ReadAll(reader) - if !assert.NoError(t, err) { - return - } - - raw, _ := ioutil.ReadFile("testdata/lipsum.txt") - assert.Equal(t, raw, content) -} - -func TestMemoryFile(t *testing.T) { - raw := []byte("hello world") - memory := MemoryFile{Path: "lipsum.txt", FileMode: 755, Raw: raw} - - assert.Equal(t, "lipsum.txt", memory.Name()) - assert.Equal(t, os.FileMode(755), memory.Mode()) - - reader, err := memory.Open() - if !assert.NoError(t, err) { - return - } - - defer func() { - err := reader.Close() - assert.NoError(t, err) - }() - - content, err := ioutil.ReadAll(reader) - if !assert.NoError(t, err) { - return - } - - assert.Equal(t, raw, content) -} diff --git a/x-pack/functionbeat/manager/core/bundle/testdata/lipsum.txt b/x-pack/functionbeat/manager/core/bundle/testdata/lipsum.txt deleted file mode 100644 index d86bac9de59a..000000000000 --- a/x-pack/functionbeat/manager/core/bundle/testdata/lipsum.txt +++ /dev/null @@ -1 +0,0 @@ -OK diff --git a/x-pack/functionbeat/manager/core/makezip.go b/x-pack/functionbeat/manager/core/makezip.go deleted file mode 100644 index 6f5c2c2d5309..000000000000 --- a/x-pack/functionbeat/manager/core/makezip.go +++ /dev/null @@ -1,115 +0,0 @@ -// Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one -// or more contributor license agreements. Licensed under the Elastic License; -// you may not use this file except in compliance with the Elastic License. - -package core - -import ( - "fmt" - - yaml "gopkg.in/yaml.v2" - - "github.com/elastic/beats/v7/libbeat/cfgfile" - "github.com/elastic/beats/v7/libbeat/cmd/instance" - "github.com/elastic/beats/v7/x-pack/functionbeat/config" - "github.com/elastic/beats/v7/x-pack/functionbeat/manager/core/bundle" - "github.com/elastic/elastic-agent-libs/keystore" -) - -func rawYaml() ([]byte, error) { - // Load the configuration file from disk with all the settings, - // the function takes care of using -c. - rawConfig, err := cfgfile.Load("", config.Overrides) - if err != nil { - return nil, err - } - var config map[string]interface{} - if err := rawConfig.Unpack(&config); err != nil { - return nil, err - } - - res, err := yaml.Marshal(config) - if err != nil { - return nil, err - } - - return res, nil -} - -// MakeZip creates a zip from the the current artifacts and the currently available configuration. -func MakeZip( - packageUncompressedLimit int64, - packageCompressedLimit int64, - providerResources []bundle.Resource, -) ([]byte, error) { - if len(providerResources) == 0 { - return nil, fmt.Errorf("no provider specific resources are set") - } - - rawConfig, err := rawYaml() - if err != nil { - return nil, err - } - - resources := append( - providerResources, - &bundle.MemoryFile{Path: "functionbeat.yml", Raw: rawConfig, FileMode: 0766}, - ) - - resources, err = addKeystoreIfConfigured(resources) - if err != nil { - return nil, err - } - - bundle := bundle.NewZipWithLimits( - packageUncompressedLimit, - packageCompressedLimit, - resources...) - - content, err := bundle.Bytes() - if err != nil { - return nil, err - } - return content, nil -} - -func addKeystoreIfConfigured(resources []bundle.Resource) ([]bundle.Resource, error) { - ksPackager, err := keystorePackager() - if err != nil { - return nil, err - } - - rawKeystore, err := ksPackager.Package() - if err != nil { - return nil, err - } - - if len(rawKeystore) > 0 { - resources = append(resources, &bundle.MemoryFile{ - Path: ksPackager.ConfiguredPath(), - Raw: rawKeystore, - FileMode: 0600, - }) - } - - return resources, nil -} - -func keystorePackager() (keystore.Packager, error) { - cfg, err := cfgfile.Load("", config.Overrides) - if err != nil { - return nil, fmt.Errorf("error loading config file: %v", err) - } - - store, err := instance.LoadKeystore(cfg, "functionbeat") - if err != nil { - return nil, fmt.Errorf("cannot load the keystore for packaging: %w", err) - } - - packager, ok := store.(keystore.Packager) - if !ok { - return nil, fmt.Errorf("the configured keystore cannot be packaged") - } - - return packager, nil -} diff --git a/x-pack/functionbeat/manager/executor/executor.go b/x-pack/functionbeat/manager/executor/executor.go deleted file mode 100644 index 75de2d776b1c..000000000000 --- a/x-pack/functionbeat/manager/executor/executor.go +++ /dev/null @@ -1,112 +0,0 @@ -// Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one -// or more contributor license agreements. Licensed under the Elastic License; -// you may not use this file except in compliance with the Elastic License. - -package executor - -import ( - "errors" - - "github.com/elastic/elastic-agent-libs/logp" -) - -var ( - // ErrNeverRun is returned if the step was never run. - ErrNeverRun = errors.New("executor was never executed") - // ErrCannotAdd is returned if the executor had already ran and a new operation is added. - ErrCannotAdd = errors.New("cannot add to an already executed executor") - // ErrAlreadyExecuted is returned if it has already run. - ErrAlreadyExecuted = errors.New("executor already executed") -) - -// Context holds the information of each execution step. -type Context interface{} - -// Executor tries to execute operations. If an operation fails, everything is rolled back. -type Executor struct { - operations []doer - undos []undoer - completed bool - log *logp.Logger -} - -type doer interface { - Execute(Context) error -} - -type undoer interface { - Rollback(Context) error -} - -// NewExecutor return a new executor. -func NewExecutor(log *logp.Logger) *Executor { - if log == nil { - log = logp.NewLogger("") - } - - log = log.Named("executor") - return &Executor{log: log} -} - -// Execute executes all operations. If something fail it rolls back. -func (e *Executor) Execute(ctx Context) (err error) { - e.log.Debugf("The executor is executing '%d' operations for converging state", len(e.operations)) - if e.IsCompleted() { - return ErrAlreadyExecuted - } - for _, operation := range e.operations { - err = operation.Execute(ctx) - if err != nil { - break - } - v, ok := operation.(undoer) - if ok { - e.undos = append(e.undos, v) - } - } - if err == nil { - e.log.Debug("All operations successful") - } - e.markCompleted() - return err -} - -// Rollback rolls back executed operations. -func (e *Executor) Rollback(ctx Context) (err error) { - e.log.Debugf("The executor is rolling back previous execution, '%d' operations to rollback", len(e.undos)) - if !e.IsCompleted() { - return ErrNeverRun - } - for i := len(e.undos) - 1; i >= 0; i-- { - operation := e.undos[i] - err = operation.Rollback(ctx) - if err != nil { - break - } - } - - if err == nil { - e.log.Debug("The rollback is successful") - } else { - e.log.Debug("The rollback is incomplete") - } - return err -} - -// Add adds new operation to execute. -func (e *Executor) Add(operation ...doer) error { - if e.IsCompleted() { - return ErrCannotAdd - } - e.operations = append(e.operations, operation...) - return nil -} - -func (e *Executor) markCompleted() { - e.completed = true -} - -// IsCompleted returns if all operations are completed. -func (e *Executor) IsCompleted() bool { - return e.completed -} diff --git a/x-pack/functionbeat/manager/executor/executor_test.go b/x-pack/functionbeat/manager/executor/executor_test.go deleted file mode 100644 index 024ef79af1d5..000000000000 --- a/x-pack/functionbeat/manager/executor/executor_test.go +++ /dev/null @@ -1,181 +0,0 @@ -// Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one -// or more contributor license agreements. Licensed under the Elastic License; -// you may not use this file except in compliance with the Elastic License. - -package executor - -import ( - "errors" - "testing" - - "github.com/stretchr/testify/assert" - "github.com/stretchr/testify/mock" -) - -type MockUndoer struct { - mock.Mock -} - -func (m *MockUndoer) Execute(_ Context) error { - args := m.Called() - return args.Error(0) -} - -func (m *MockUndoer) Rollback(_ Context) error { - args := m.Called() - return args.Error(0) -} - -type MockDoer struct { - mock.Mock -} - -func (m *MockDoer) Execute(_ Context) error { - args := m.Called() - return args.Error(0) -} - -func TestExecutor(t *testing.T) { - t.Run("executes all the tasks", testAll) - t.Run("stop execution on first error", testError) - t.Run("stop execution and allow rollback on undoer", testUndoer) - t.Run("stop rollback if one rollback fail", testFailRollback) - t.Run("an execution cannot be run twice", testCannotRunTwice) - t.Run("cannot add operation to a completed execution", testCannotAddCompleted) -} - -func testAll(t *testing.T) { - ctx := struct{}{} - executor := NewExecutor(nil) - m1 := &MockDoer{} - m1.On("Execute").Return(nil) - - m2 := &MockDoer{} - m2.On("Execute").Return(nil) - - executor.Add(m1, m2) - err := executor.Execute(ctx) - if !assert.NoError(t, err) { - return - } - - m1.AssertExpectations(t) - m2.AssertExpectations(t) -} - -func testError(t *testing.T) { - ctx := struct{}{} - executor := NewExecutor(nil) - m1 := &MockDoer{} - m1.On("Execute").Return(nil) - - m2 := &MockDoer{} - e := errors.New("something bad") - m2.On("Execute").Return(e) - - m3 := &MockDoer{} - executor.Add(m1, m2, m3) - err := executor.Execute(ctx) - if assert.Equal(t, e, err) { - return - } - - m1.AssertExpectations(t) - m2.AssertExpectations(t) - m3.AssertExpectations(t) -} - -func testUndoer(t *testing.T) { - ctx := struct{}{} - executor := NewExecutor(nil) - m1 := &MockUndoer{} - m1.On("Execute").Return(nil) - m1.On("Rollback").Return(nil) - - m2 := &MockDoer{} - e := errors.New("something bad") - m2.On("Execute").Return(e) - - m3 := &MockDoer{} - executor.Add(m1, m2, m3) - err := executor.Execute(ctx) - if !assert.Equal(t, e, err) { - return - } - - err = executor.Rollback(ctx) - if !assert.NoError(t, err) { - return - } - - m1.AssertExpectations(t) - m2.AssertExpectations(t) - m3.AssertExpectations(t) -} - -func testFailRollback(t *testing.T) { - ctx := struct{}{} - e := errors.New("error on execution") - e2 := errors.New("error on rollback") - - executor := NewExecutor(nil) - m1 := &MockUndoer{} - m1.On("Execute").Return(nil) - - m2 := &MockUndoer{} - m2.On("Execute").Return(nil) - m2.On("Rollback").Return(e2) - - m3 := &MockUndoer{} - m3.On("Execute").Return(e) - - executor.Add(m1, m2, m3) - - err := executor.Execute(ctx) - if !assert.Equal(t, e, err) { - return - } - - err = executor.Rollback(ctx) - if !assert.Error(t, err) { - return - } - - m1.AssertExpectations(t) - m2.AssertExpectations(t) - m3.AssertExpectations(t) -} - -func testCannotRunTwice(t *testing.T) { - ctx := struct{}{} - executor := NewExecutor(nil) - m1 := &MockDoer{} - m1.On("Execute").Return(nil) - - executor.Add(m1) - err := executor.Execute(ctx) - if !assert.NoError(t, err) { - return - } - - m1.AssertExpectations(t) - - assert.True(t, executor.IsCompleted()) - assert.Error(t, ErrAlreadyExecuted, executor.Execute(ctx)) -} - -func testCannotAddCompleted(t *testing.T) { - executor := NewExecutor(nil) - m1 := &MockDoer{} - m1.On("Execute").Return(nil) - - executor.Add(m1) - err := executor.Execute(struct{}{}) - if !assert.NoError(t, err) { - return - } - - m1.AssertExpectations(t) - - assert.Error(t, executor.Add(&MockDoer{})) -} diff --git a/x-pack/functionbeat/provider/aws/aws/api_gateway_proxy.go b/x-pack/functionbeat/provider/aws/aws/api_gateway_proxy.go deleted file mode 100644 index 5b9cd9734a5f..000000000000 --- a/x-pack/functionbeat/provider/aws/aws/api_gateway_proxy.go +++ /dev/null @@ -1,96 +0,0 @@ -// Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one -// or more contributor license agreements. Licensed under the Elastic License; -// you may not use this file except in compliance with the Elastic License. - -package aws - -import ( - "context" - "encoding/json" - "net/http" - - "github.com/aws/aws-lambda-go/events" - "github.com/aws/aws-lambda-go/lambda" - - "github.com/elastic/beats/v7/libbeat/common/cfgwarn" - "github.com/elastic/beats/v7/libbeat/feature" - "github.com/elastic/beats/v7/libbeat/publisher/pipeline" - "github.com/elastic/beats/v7/x-pack/functionbeat/function/provider" - "github.com/elastic/beats/v7/x-pack/functionbeat/function/telemetry" - "github.com/elastic/beats/v7/x-pack/functionbeat/provider/aws/aws/transformer" - conf "github.com/elastic/elastic-agent-libs/config" - "github.com/elastic/elastic-agent-libs/logp" -) - -type message struct { - RequestID string `json:"request_id"` - Status int `json:"status"` - Message string `json:"message"` -} - -// APIGatewayProxy receives events from the web service and forward them to elasticsearch. -type APIGatewayProxy struct { - log *logp.Logger -} - -// NewAPIGatewayProxy creates a new function to receives events from the web api gateway. -func NewAPIGatewayProxy(provider provider.Provider, config *conf.C) (provider.Function, error) { - cfgwarn.Experimental("The api_gateway_proxy trigger is experimental.") - return &APIGatewayProxy{log: logp.NewLogger("api gateway proxy")}, nil -} - -// APIGatewayProxyDetails returns the details of the feature. -func APIGatewayProxyDetails() feature.Details { - return feature.MakeDetails("API Gateway proxy trigger", "receive events from the api gateway proxy", feature.Experimental) -} - -// Run starts the lambda function and wait for web triggers. -func (a *APIGatewayProxy) Run(_ context.Context, client pipeline.ISyncClient, telemetry telemetry.T) error { - telemetry.AddTriggeredFunction() - - lambda.Start(a.createHandler(client)) - return nil -} - -func (a *APIGatewayProxy) createHandler( - client pipeline.ISyncClient, -) func(request events.APIGatewayProxyRequest) (events.APIGatewayProxyResponse, error) { - return func(request events.APIGatewayProxyRequest) (events.APIGatewayProxyResponse, error) { - a.log.Debugf("The handler receives a new event from the gateway (requestID: %s)", request.RequestContext.RequestID) - event := transformer.APIGatewayProxyRequest(request) - - if err := client.Publish(event); err != nil { - a.log.Errorf("could not publish event to the pipeline, error: %+v", err) - return buildResponse( - http.StatusInternalServerError, - "an error occurred when sending the event.", - request.RequestContext.RequestID, - ), err - } - client.Wait() - return buildResponse( - http.StatusOK, - "event received successfully.", - request.RequestContext.RequestID, - ), nil - } -} - -func buildResponse( - statusCode int, - responseMsg string, - requestID string, -) events.APIGatewayProxyResponse { - body, _ := json.Marshal(message{Status: statusCode, Message: responseMsg, RequestID: requestID}) - - return events.APIGatewayProxyResponse{ - StatusCode: statusCode, - Headers: map[string]string{"Content-Type": "application/json"}, - Body: string(body), - } -} - -// Name return the name of the lambda function. -func (a *APIGatewayProxy) Name() string { - return "api_gateway_proxy" -} diff --git a/x-pack/functionbeat/provider/aws/aws/api_gateway_proxy_test.go b/x-pack/functionbeat/provider/aws/aws/api_gateway_proxy_test.go deleted file mode 100644 index 640dc949e0cc..000000000000 --- a/x-pack/functionbeat/provider/aws/aws/api_gateway_proxy_test.go +++ /dev/null @@ -1,92 +0,0 @@ -// Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one -// or more contributor license agreements. Licensed under the Elastic License; -// you may not use this file except in compliance with the Elastic License. - -package aws - -import ( - "encoding/json" - "errors" - "net/http" - "testing" - - "github.com/aws/aws-lambda-go/events" - "github.com/stretchr/testify/assert" - - "github.com/elastic/beats/v7/x-pack/functionbeat/function/provider" - conf "github.com/elastic/elastic-agent-libs/config" -) - -func TestAPIGatewayProxy(t *testing.T) { - cfg := conf.MustNewConfigFrom(map[string]interface{}{ - "name": "foobar", - }) - - t.Run("when publish is succesful", func(t *testing.T) { - t.SkipNow() - client := &arrayBackedClient{} - s, err := NewAPIGatewayProxy(&provider.DefaultProvider{}, cfg) - if !assert.NoError(t, err) { - return - } - - c, _ := s.(*APIGatewayProxy) - handler := c.createHandler(client) - res, err := handler(generateAPIGatewayProxyEvent()) - assert.NoError(t, err) - assert.Equal(t, res.StatusCode, http.StatusOK) - ty, _ := res.Headers["Content-Type"] - assert.Equal(t, "application/json", ty) - - message, err := unserializeResponse(res.Body) - if !assert.NoError(t, err) { - return - } - - assert.Equal(t, "1234", message.RequestID) - assert.Equal(t, "event received successfully.", message.Message) - assert.Equal(t, http.StatusOK, message.Status) - }) - - t.Run("when publish is not succesful", func(t *testing.T) { - e := errors.New("something bad") - client := &arrayBackedClient{err: e} - - s, err := NewAPIGatewayProxy(&provider.DefaultProvider{}, cfg) - if !assert.NoError(t, err) { - return - } - - c, _ := s.(*APIGatewayProxy) - res, err := c.createHandler(client)(generateAPIGatewayProxyEvent()) - assert.Equal(t, e, err) - assert.Equal(t, http.StatusInternalServerError, res.StatusCode) - ty, _ := res.Headers["Content-Type"] - assert.Equal(t, "application/json", ty) - - message, err := unserializeResponse(res.Body) - if !assert.NoError(t, err) { - return - } - - assert.Equal(t, "1234", message.RequestID) - assert.Equal(t, "an error occurred when sending the event.", message.Message) - assert.Equal(t, http.StatusInternalServerError, message.Status) - }) -} - -func generateAPIGatewayProxyEvent() events.APIGatewayProxyRequest { - return events.APIGatewayProxyRequest{ - RequestContext: events.APIGatewayProxyRequestContext{ - RequestID: "1234", - }, - } -} - -func unserializeResponse(raw string) (*message, error) { - message := &message{} - if err := json.Unmarshal([]byte(raw), message); err != nil { - return nil, err - } - return message, nil -} diff --git a/x-pack/functionbeat/provider/aws/aws/cloudwatch_kinesis.go b/x-pack/functionbeat/provider/aws/aws/cloudwatch_kinesis.go deleted file mode 100644 index adde8793ec5e..000000000000 --- a/x-pack/functionbeat/provider/aws/aws/cloudwatch_kinesis.go +++ /dev/null @@ -1,117 +0,0 @@ -// Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one -// or more contributor license agreements. Licensed under the Elastic License; -// you may not use this file except in compliance with the Elastic License. - -package aws - -import ( - "context" - - "github.com/aws/aws-lambda-go/events" - lambdarunner "github.com/aws/aws-lambda-go/lambda" - "github.com/awslabs/goformation/v7/cloudformation" - "github.com/awslabs/goformation/v7/cloudformation/iam" - - "github.com/elastic/beats/v7/libbeat/feature" - "github.com/elastic/beats/v7/libbeat/publisher/pipeline" - "github.com/elastic/beats/v7/x-pack/functionbeat/function/provider" - "github.com/elastic/beats/v7/x-pack/functionbeat/function/telemetry" - "github.com/elastic/beats/v7/x-pack/functionbeat/provider/aws/aws/transformer" - conf "github.com/elastic/elastic-agent-libs/config" - "github.com/elastic/elastic-agent-libs/logp" -) - -// CloudwatchKinesis receives events from a kinesis stream and forward them to elasticsearch. -type CloudwatchKinesis struct { - *Kinesis - log *logp.Logger - config *CloudwatchKinesisConfig -} - -// CloudwatchKinesisConfig stores the configuration of Kinesis and additional options on decompressing data. -type CloudwatchKinesisConfig struct { - *KinesisConfig `config:",inline"` - Base64Encoded bool `config:"base64_encoded"` - Compressed bool `config:"compressed"` -} - -// NewCloudwatchKinesis creates a new function to receives events from a kinesis stream. -func NewCloudwatchKinesis(provider provider.Provider, cfg *conf.C) (provider.Function, error) { - config := defaultCloudwatchKinesisConfig() - if err := cfg.Unpack(config); err != nil { - return nil, err - } - - logger := logp.NewLogger("cloudwatch_logs_kinesis") - - return &CloudwatchKinesis{ - Kinesis: &Kinesis{ - config: config.KinesisConfig, - log: logger, - }, - log: logger, - config: config, - }, nil -} - -func defaultCloudwatchKinesisConfig() *CloudwatchKinesisConfig { - return &CloudwatchKinesisConfig{ - &KinesisConfig{ - LambdaConfig: DefaultLambdaConfig, - }, - false, - true, - } -} - -// CloudwatchKinesisDetails returns the details of the feature. -func CloudwatchKinesisDetails() feature.Details { - return feature.MakeDetails("Cloudwatch logs via Kinesis trigger", "receive Cloudwatch logs from a Kinesis stream", feature.Experimental) -} - -// Run starts the lambda function and wait for web triggers. -func (c *CloudwatchKinesis) Run(_ context.Context, client pipeline.ISyncClient, t telemetry.T) error { - t.AddTriggeredFunction() - - lambdarunner.Start(c.createHandler(client)) - return nil -} - -func (c *CloudwatchKinesis) createHandler(client pipeline.ISyncClient) func(request events.KinesisEvent) error { - return func(request events.KinesisEvent) error { - c.log.Debugf("The handler receives %d events", len(request.Records)) - - events, err := transformer.CloudwatchKinesisEvent(request, c.config.Base64Encoded, c.config.Compressed) - if err != nil { - return err - } - - if err := client.PublishAll(events); err != nil { - c.log.Errorf("Could not publish events to the pipeline, error: %+v", err) - return err - } - client.Wait() - return nil - } -} - -// Name return the name of the lambda function. -func (c *CloudwatchKinesis) Name() string { - return "cloudwatch_logs_kinesis" -} - -// LambdaConfig returns the configuration to use when creating the lambda. -func (c *CloudwatchKinesis) LambdaConfig() *LambdaConfig { - return c.config.LambdaConfig -} - -// Template returns the cloudformation template for configuring the service with the specified -// triggers. -func (c *CloudwatchKinesis) Template() *cloudformation.Template { - return c.Kinesis.Template() -} - -// Policies returns a slice of policy to add to the lambda role. -func (c *CloudwatchKinesis) Policies() []iam.Role_Policy { - return c.Kinesis.Policies() -} diff --git a/x-pack/functionbeat/provider/aws/aws/cloudwatch_logs.go b/x-pack/functionbeat/provider/aws/aws/cloudwatch_logs.go deleted file mode 100644 index 83f8f0117042..000000000000 --- a/x-pack/functionbeat/provider/aws/aws/cloudwatch_logs.go +++ /dev/null @@ -1,230 +0,0 @@ -// Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one -// or more contributor license agreements. Licensed under the Elastic License; -// you may not use this file except in compliance with the Elastic License. - -package aws - -import ( - "context" - "encoding/json" - "errors" - "fmt" - "regexp" - "strconv" - - "github.com/aws/aws-lambda-go/events" - lambdarunner "github.com/aws/aws-lambda-go/lambda" - "github.com/awslabs/goformation/v7/cloudformation" - "github.com/awslabs/goformation/v7/cloudformation/iam" - "github.com/awslabs/goformation/v7/cloudformation/lambda" - "github.com/awslabs/goformation/v7/cloudformation/policies" - - "github.com/elastic/beats/v7/libbeat/feature" - "github.com/elastic/beats/v7/libbeat/publisher/pipeline" - "github.com/elastic/beats/v7/x-pack/functionbeat/function/provider" - "github.com/elastic/beats/v7/x-pack/functionbeat/function/telemetry" - "github.com/elastic/beats/v7/x-pack/functionbeat/provider/aws/aws/transformer" - conf "github.com/elastic/elastic-agent-libs/config" - "github.com/elastic/elastic-agent-libs/logp" -) - -var ( - logGroupNamePattern = "^[\\.\\-_/#A-Za-z0-9]+$" - logGroupNameRE = regexp.MustCompile(logGroupNamePattern) -) - -// CloudwatchLogsConfig is the configuration for the cloudwatchlogs event type. -type CloudwatchLogsConfig struct { - Triggers []*CloudwatchLogsTriggerConfig `config:"triggers"` - Description string `config:"description"` - Name string `config:"name" validate:"nonzero,required"` - LambdaConfig *LambdaConfig `config:",inline"` -} - -// CloudwatchLogsTriggerConfig is the configuration for the specific triggers for cloudwatch. -type CloudwatchLogsTriggerConfig struct { - LogGroupName logGroupName `config:"log_group_name" validate:"nonzero,required"` - FilterPattern string `config:"filter_pattern"` -} - -// Validate validates the configuration. -func (cfg *CloudwatchLogsConfig) Validate() error { - if len(cfg.Triggers) == 0 { - return errors.New("you need to specify at least one trigger") - } - return nil -} - -// DOC: see validations rules at https://docs.aws.amazon.com/AmazonCloudWatchLogs/latest/APIReference/API_CreateLogGroup.html -type logGroupName string - -// Unpack takes a string and validate the log group format. -func (l *logGroupName) Unpack(s string) error { - const max = 512 - const min = 1 - - if len(s) > max { - return fmt.Errorf("log group name '%s' is too long, maximum length is %d", s, max) - } - - if len(s) < min { - return fmt.Errorf("log group name too short, minimum length is %d", min) - } - - if !logGroupNameRE.MatchString(s) { - return fmt.Errorf( - "invalid characters in log group name '%s', name must match regular expression: '%s'", - s, - logGroupNamePattern, - ) - } - *l = logGroupName(s) - return nil -} - -// CloudwatchLogs receives CloudwatchLogs events from a lambda function and forward the logs to -// an Elasticsearch cluster. -type CloudwatchLogs struct { - log *logp.Logger - config *CloudwatchLogsConfig -} - -// NewCloudwatchLogs create a new function to listen to cloudwatch logs events. -func NewCloudwatchLogs(provider provider.Provider, cfg *conf.C) (provider.Function, error) { - config := &CloudwatchLogsConfig{ - LambdaConfig: DefaultLambdaConfig, - } - if err := cfg.Unpack(config); err != nil { - return nil, err - } - return &CloudwatchLogs{log: logp.NewLogger("cloudwatch_logs"), config: config}, nil -} - -// CloudwatchLogsDetails returns the details of the feature. -func CloudwatchLogsDetails() feature.Details { - return feature.MakeDetails("Cloudwatch Logs trigger", "receive events from cloudwatch logs.", feature.Stable) -} - -// Run start the AWS lambda handles and will transform any events received to the pipeline. -func (c *CloudwatchLogs) Run(_ context.Context, client pipeline.ISyncClient, t telemetry.T) error { - t.AddTriggeredFunction() - - lambdarunner.Start(c.createHandler(client)) - return nil -} - -func (c *CloudwatchLogs) createHandler( - client pipeline.ISyncClient, -) func(request events.CloudwatchLogsEvent) error { - return func(request events.CloudwatchLogsEvent) error { - parsedEvent, err := request.AWSLogs.Parse() - if err != nil { - c.log.Errorf("Could not parse events from cloudwatch logs, error: %+v", err) - return err - } - - c.log.Debugf( - "The handler receives %d events (logStream: %s, owner: %s, logGroup: %s, messageType: %s)", - len(parsedEvent.LogEvents), - parsedEvent.LogStream, - parsedEvent.Owner, - parsedEvent.LogGroup, - parsedEvent.MessageType, - ) - - events := transformer.CloudwatchLogs(parsedEvent) - - if err := client.PublishAll(events); err != nil { - c.log.Errorf("Could not publish events to the pipeline, error: %+v", err) - return err - } - client.Wait() - return nil - } -} - -// Name returns the name of the function. -func (c CloudwatchLogs) Name() string { - return "cloudwatch_logs" -} - -// AWSLogsSubscriptionFilter overrides the type from goformation to allow to pass an empty string. -// The API support an empty string, but requires one, the original type does not permit that. -type AWSLogsSubscriptionFilter struct { - DestinationArn string `json:"DestinationArn,omitempty"` - FilterPattern string `json:"FilterPattern"` - LogGroupName string `json:"LogGroupName,omitempty"` -} - -// MarshalJSON is a custom JSON marshalling hook that embeds this object into -// an AWS CloudFormation JSON resource's 'Properties' field and adds a 'Type'. -func (r AWSLogsSubscriptionFilter) MarshalJSON() ([]byte, error) { - type Properties AWSLogsSubscriptionFilter - return json.Marshal(&struct { - Type string - Properties Properties - DeletionPolicy policies.DeletionPolicy `json:"DeletionPolicy,omitempty"` - }{ - Type: r.AWSCloudFormationType(), - Properties: (Properties)(r), - }) -} - -// AWSCloudFormationType return the AWS type. -func (r *AWSLogsSubscriptionFilter) AWSCloudFormationType() string { - return "AWS::Logs::SubscriptionFilter" -} - -// Template returns the cloudformation template for configuring the service with the specified triggers. -func (c *CloudwatchLogs) Template() *cloudformation.Template { - prefix := func(suffix string) string { - return NormalizeResourceName("fnb" + c.config.Name + suffix) - } - - template := cloudformation.NewTemplate() - for idx, trigger := range c.config.Triggers { - // doc: https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-lambda-permission.html - template.Resources[prefix("Permission"+strconv.Itoa(idx))] = &lambda.Permission{ - Action: "lambda:InvokeFunction", - FunctionName: cloudformation.GetAtt(prefix(""), "Arn"), - Principal: cloudformation.Join("", []string{ - "logs.", - cloudformation.Ref("AWS::Region"), // Use the configuration region. - ".", - cloudformation.Ref("AWS::URLSuffix"), // awsamazon.com or .com.ch - }), - SourceArn: cloudformation.JoinPtr( - "", - []string{ - "arn:", - cloudformation.Ref("AWS::Partition"), - ":logs:", - cloudformation.Ref("AWS::Region"), - ":", - cloudformation.Ref("AWS::AccountId"), - ":log-group:", - string(trigger.LogGroupName), - ":*", - }, - ), - } - - // doc: https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-logs-subscriptionfilter.html - template.Resources[prefix("SF")+NormalizeResourceName(string(trigger.LogGroupName))] = &AWSLogsSubscriptionFilter{ - DestinationArn: cloudformation.GetAtt(prefix(""), "Arn"), - FilterPattern: trigger.FilterPattern, - LogGroupName: string(trigger.LogGroupName), - } - } - return template -} - -// LambdaConfig returns the configuration to use when creating the lambda. -func (c *CloudwatchLogs) LambdaConfig() *LambdaConfig { - return c.config.LambdaConfig -} - -// Policies returns a slice of policy to add to the lambda. -func (c *CloudwatchLogs) Policies() []iam.Role_Policy { - return []iam.Role_Policy{} -} diff --git a/x-pack/functionbeat/provider/aws/aws/cloudwatch_logs_test.go b/x-pack/functionbeat/provider/aws/aws/cloudwatch_logs_test.go deleted file mode 100644 index b9613720b838..000000000000 --- a/x-pack/functionbeat/provider/aws/aws/cloudwatch_logs_test.go +++ /dev/null @@ -1,153 +0,0 @@ -// Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one -// or more contributor license agreements. Licensed under the Elastic License; -// you may not use this file except in compliance with the Elastic License. - -package aws - -import ( - "bytes" - "compress/gzip" - "encoding/base64" - "encoding/json" - "errors" - "testing" - "time" - - "github.com/aws/aws-lambda-go/events" - "github.com/stretchr/testify/assert" - - "github.com/elastic/beats/v7/libbeat/beat" - "github.com/elastic/beats/v7/libbeat/common" - "github.com/elastic/beats/v7/x-pack/functionbeat/function/provider" - conf "github.com/elastic/elastic-agent-libs/config" -) - -type arrayBackedClient struct { - Events []beat.Event - err error -} - -func (a *arrayBackedClient) Publish(event beat.Event) error { - if a.err != nil { - return a.err - } - a.Events = append(a.Events, event) - return nil -} - -func (a *arrayBackedClient) PublishAll(events []beat.Event) error { - if a.err != nil { - return a.err - } - a.Events = append(a.Events, events...) - return nil -} - -func (a *arrayBackedClient) Wait() { return } -func (a *arrayBackedClient) Close() error { return nil } - -func TestCloudwatchLogs(t *testing.T) { - cfg := conf.MustNewConfigFrom(map[string]interface{}{ - "name": "foobar", - "description": "my long description", - "role": "arn:aws:iam::000000000000:role/functionbeat", - "triggers": []map[string]interface{}{ - map[string]interface{}{ - "log_group_name": "foo", - "filter_name": "bar", - }, - }, - }) - - t.Run("when publish is succesful", func(t *testing.T) { - client := &arrayBackedClient{} - cwl, err := NewCloudwatchLogs(&provider.DefaultProvider{}, cfg) - if !assert.NoError(t, err) { - return - } - - c, _ := cwl.(*CloudwatchLogs) - handler := c.createHandler(client) - - err = handler(generateCloudwatchLogRawEvent()) - - assert.NoError(t, err) - }) - - t.Run("when publish is not succesful", func(t *testing.T) { - e := errors.New("something bad") - client := &arrayBackedClient{err: e} - cwl, err := NewCloudwatchLogs(&provider.DefaultProvider{}, cfg) - if !assert.NoError(t, err) { - return - } - - c, _ := cwl.(*CloudwatchLogs) - handler := c.createHandler(client) - - err = handler(generateCloudwatchLogRawEvent()) - - assert.Equal(t, e, err) - }) -} - -func generateCloudwatchLogRawEvent() events.CloudwatchLogsEvent { - rawEvent := events.CloudwatchLogsData{ - Owner: "foobar", - LogGroup: "foo", - LogStream: "/var/foobar", - LogEvents: []events.CloudwatchLogsLogEvent{ - events.CloudwatchLogsLogEvent{ - ID: "1234", - Timestamp: time.Now().Unix(), - Message: "hello world", - }, - }, - } - - b, _ := json.Marshal(&rawEvent) - - data := new(bytes.Buffer) - encoder := base64.NewEncoder(base64.StdEncoding, data) - zw := gzip.NewWriter(encoder) - zw.Write(b) - zw.Close() - encoder.Close() - - return events.CloudwatchLogsEvent{ - AWSLogs: events.CloudwatchLogsRawData{ - Data: data.String(), - }, - } -} - -func TestLogGroupName(t *testing.T) { - t.Run("valid name", func(t *testing.T) { - l := logGroupName("") - err := l.Unpack("helloworld") - if !assert.NoError(t, err) { - return - } - - assert.Equal(t, logGroupName("helloworld"), l) - }) - - t.Run("fail if contains invalid chars", func(t *testing.T) { - l := logGroupName("") - err := l.Unpack("hello world") - assert.Error(t, err) - }) - - t.Run("fail if too short", func(t *testing.T) { - l := logGroupName("") - err := l.Unpack("") - assert.Error(t, err) - }) - - t.Run("fail if above 512 chars", func(t *testing.T) { - r, _ := common.RandomBytes(513) - l := logGroupName("") - err := l.Unpack(string(r[:513])) - assert.Error(t, err) - }) -} diff --git a/x-pack/functionbeat/provider/aws/aws/config.go b/x-pack/functionbeat/provider/aws/aws/config.go deleted file mode 100644 index c7a7486d7362..000000000000 --- a/x-pack/functionbeat/provider/aws/aws/config.go +++ /dev/null @@ -1,186 +0,0 @@ -// Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one -// or more contributor license agreements. Licensed under the Elastic License; -// you may not use this file except in compliance with the Elastic License. - -package aws - -import ( - "fmt" - "regexp" - "strings" - "time" - "unicode" - "unicode/utf8" - - "github.com/dustin/go-humanize" - - "github.com/elastic/beats/v7/libbeat/common/cfgwarn" - awscommon "github.com/elastic/beats/v7/x-pack/libbeat/common/aws" -) - -// Config expose the configuration option the AWS provider. -type Config struct { - DeployBucket bucket `config:"deploy_bucket" validate:"nonzero,required"` - Region string `config:"region"` - Credentials awscommon.ConfigAWS `config:",inline"` -} - -func DefaultConfig() *Config { - return &Config{ - Credentials: awscommon.ConfigAWS{ - Endpoint: "s3.amazonaws.com", - }, - } -} - -func (c *Config) Validate() error { - if c.Credentials.Endpoint == "" { - return fmt.Errorf("functionbeat.providers.aws.endpoint cannot be empty") - } - return nil -} - -// maxMegabytes maximums memory that a lambda can use. -const maxMegabytes = 3008 - -// DefaultLambdaConfig confguration for AWS lambda function. -var ( - DefaultLambdaConfig = &LambdaConfig{ - MemorySize: 128 * 1024 * 1024, - Timeout: time.Second * 3, - Concurrency: 5, - } - - // Source: https://docs.aws.amazon.com/lambda/latest/dg/API_CreateFunction.html#SSS-CreateFunction-request-Role - arnRolePattern = "arn:(aws[a-zA-Z-]*)?:iam::\\d{12}:role/?[a-zA-Z_0-9+=,.@\\-_/]+" - roleRE = regexp.MustCompile(arnRolePattern) - - // Chars for resource name anything else will be replaced. - validChars = regexp.MustCompile("[^a-zA-Z0-9]") -) - -// LambdaConfig stores the common configuration of Lambda functions. -type LambdaConfig struct { - Concurrency int `config:"concurrency" validate:"min=0,max=1000"` - DeadLetterConfig *deadLetterConfig `config:"dead_letter_config"` - Description string `config:"description"` - MemorySize MemSizeFactor64 `config:"memory_size"` - Timeout time.Duration `config:"timeout" validate:"nonzero,positive"` - Role string `config:"role"` - VPCConfig *vpcConfig `config:"virtual_private_cloud"` - Tags map[string]string `config:"tags"` -} - -// Validate checks a LambdaConfig -func (c *LambdaConfig) Validate() error { - if c.MemorySize.Megabytes() == 0 { - return fmt.Errorf("'memory_size' need to be higher than 0 and must be a factor 64") - } - - if c.MemorySize.Megabytes() > maxMegabytes { - return fmt.Errorf("'memory_size' must be lower than %d", maxMegabytes) - } - - if c.Role != "" && !roleRE.MatchString(c.Role) { - return fmt.Errorf("invalid role: '%s', name must match pattern %s", c.Role, arnRolePattern) - } - - return validateTags(c.Tags) -} - -type deadLetterConfig struct { - TargetArn string `config:"target_arn"` -} - -type vpcConfig struct { - SecurityGroupIDs []string `config:"security_group_ids" validate:"required"` - SubnetIDs []string `config:"subnet_ids" validate:"required"` -} - -func validateTags(tags map[string]string) error { - for key, val := range tags { - if strings.HasPrefix(key, "aws:") { - return fmt.Errorf("key '%s' cannot be prefixed with 'aws:'", key) - } - if strings.HasPrefix(val, "aws:") { - return fmt.Errorf("value '%s' cannot be prefixed with 'aws:'", val) - } - keyLen := utf8.RuneCountInString(key) - if keyLen > 127 { - return fmt.Errorf("too long key; expected 127 chars, but got %d", keyLen) - } - valLen := utf8.RuneCountInString(val) - if valLen > 255 { - return fmt.Errorf("too long value; expected 255 chars, but got %d", valLen) - } - } - - return nil -} - -// MemSizeFactor64 implements a human understandable format for bytes but also make sure that all -// values used are a factor of 64. -type MemSizeFactor64 int - -// Unpack converts a size defined from a human readable format into bytes and verifies that the value -// is a multiple of 64. If the value is not multple of 64, it returns an error. -func (m *MemSizeFactor64) Unpack(v string) error { - sz, err := humanize.ParseBytes(v) - if isRawBytes(v) { - cfgwarn.Deprecate("7.0.0", "size now requires a unit (KiB, MiB, etc...), current value: %s.", v) - } - if err != nil { - return err - } - - if sz%64 != 0 { - return fmt.Errorf("number is not a multiple of 64, %d bytes (user value: %s)", sz, v) - } - - *m = MemSizeFactor64(sz) - return nil -} - -// Megabytes return the value in megabytes. -func (m *MemSizeFactor64) Megabytes() int { - return int(*m) / 1024 / 1024 -} - -func isRawBytes(v string) bool { - for _, c := range v { - if !unicode.IsDigit(c) { - return false - } - } - return true -} - -type bucket string - -// Do some high level validation on the bucket name, they have strict validations on the name on the API side. -// DOC: https://docs.aws.amazon.com/AmazonS3/latest/dev/BucketRestrictions.html#bucketnamingrules -func (b *bucket) Unpack(s string) error { - const max = 63 - const min = 3 - if len(s) > max { - return fmt.Errorf("bucket name '%s' is too long, name are restricted to %d chars", s, max) - } - - if len(s) < min { - return fmt.Errorf("bucket name '%s' is too short, name need to be at least %d chars long", s, min) - } - - const bucketNamePattern = "^[a-z0-9][a-z0-9.\\-]{1,61}[a-z0-9]$" - var bucketRE = regexp.MustCompile(bucketNamePattern) - if !bucketRE.MatchString(s) { - return fmt.Errorf("invalid bucket name: '%s', bucket name must match pattern: '%s'", s, bucketNamePattern) - } - - *b = bucket(s) - return nil -} - -// NormalizeResourceName extracts invalid chars. -func NormalizeResourceName(s string) string { - return validChars.ReplaceAllString(s, "") -} diff --git a/x-pack/functionbeat/provider/aws/aws/config_test.go b/x-pack/functionbeat/provider/aws/aws/config_test.go deleted file mode 100644 index ef1045f188ed..000000000000 --- a/x-pack/functionbeat/provider/aws/aws/config_test.go +++ /dev/null @@ -1,135 +0,0 @@ -// Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one -// or more contributor license agreements. Licensed under the Elastic License; -// you may not use this file except in compliance with the Elastic License. - -package aws - -import ( - "fmt" - "testing" - - "github.com/stretchr/testify/assert" -) - -func TestMemSizeFactor64(t *testing.T) { - t.Run("human format", func(t *testing.T) { - t.Run("value is a factor of 64", func(t *testing.T) { - v := MemSizeFactor64(0) - err := v.Unpack("128MiB") - if !assert.NoError(t, err) { - return - } - assert.Equal(t, MemSizeFactor64(128*1024*1024), v) - }) - }) - - t.Run("raw value", func(t *testing.T) { - t.Run("value is a factor of 64", func(t *testing.T) { - v := MemSizeFactor64(0) - err := v.Unpack(fmt.Sprintf("%d", 128*1024*1024)) - if !assert.NoError(t, err) { - return - } - assert.Equal(t, MemSizeFactor64(128*1024*1024), v) - }) - - t.Run("value is not a factor of 64", func(t *testing.T) { - v := MemSizeFactor64(0) - err := v.Unpack("121") - assert.Error(t, err) - }) - }) - - t.Run("returns the value in megabyte", func(t *testing.T) { - v := MemSizeFactor64(128 * 1024 * 1024) - assert.Equal(t, 128, v.Megabytes()) - }) -} -func TestBucket(t *testing.T) { - t.Run("valid bucket name", func(t *testing.T) { - b := bucket("") - err := b.Unpack("hello-bucket") - if !assert.NoError(t, err) { - return - } - assert.Equal(t, bucket("hello-bucket"), b) - }) - - t.Run("too long", func(t *testing.T) { - b := bucket("") - err := b.Unpack("hello-bucket-abc12345566789012345678901234567890123456789012345678901234567890") - assert.Error(t, err) - }) - - t.Run("too short", func(t *testing.T) { - b := bucket("") - err := b.Unpack("he") - assert.Error(t, err) - }) - - t.Run("bucket regex pattern, disallows semi-colon", func(t *testing.T) { - b := bucket("") - err := b.Unpack("asdfdaf;dfadsfadsf") - assert.Error(t, err) - }) - - t.Run("bucket regex pattern, disallows slash", func(t *testing.T) { - b := bucket("") - err := b.Unpack("asdfdaf/dfadsfadsf") - assert.Error(t, err) - }) - - t.Run("bucket regex pattern, allows dots", func(t *testing.T) { - b := bucket("") - err := b.Unpack("this.is.a.bucket") - if !assert.NoError(t, err) { - return - } - assert.Equal(t, bucket("this.is.a.bucket"), b) - }) - - t.Run("bucket regex pattern, allows hyphens", func(t *testing.T) { - b := bucket("") - err := b.Unpack("this-is-a-bucket") - if !assert.NoError(t, err) { - return - } - assert.Equal(t, bucket("this-is-a-bucket"), b) - }) -} - -func TestNormalize(t *testing.T) { - tests := []struct { - title string - candidate string - chars string - expected string - }{ - { - title: "when the string contains invalid chars", - candidate: "/var/log-alpha/tmp:ok", - expected: "varlogalphatmpok", - }, - { - title: "when we have an empty string", - candidate: "", - expected: "", - }, - { - title: "when we don't have any invalid chars", - candidate: "hello", - expected: "hello", - }, - { - title: "when the string contains underscore", - candidate: "/var/log-alpha/tmp:ok_moreok", - expected: "varlogalphatmpokmoreok", - }, - } - - for _, test := range tests { - t.Run(test.title, func(t *testing.T) { - assert.Equal(t, test.expected, NormalizeResourceName(test.candidate)) - }) - } -} diff --git a/x-pack/functionbeat/provider/aws/aws/kinesis.go b/x-pack/functionbeat/provider/aws/aws/kinesis.go deleted file mode 100644 index b286ab214d91..000000000000 --- a/x-pack/functionbeat/provider/aws/aws/kinesis.go +++ /dev/null @@ -1,226 +0,0 @@ -// Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one -// or more contributor license agreements. Licensed under the Elastic License; -// you may not use this file except in compliance with the Elastic License. - -package aws - -import ( - "context" - "errors" - "fmt" - "sort" - "strings" - - "github.com/aws/aws-lambda-go/events" - lambdarunner "github.com/aws/aws-lambda-go/lambda" - "github.com/awslabs/goformation/v7/cloudformation" - "github.com/awslabs/goformation/v7/cloudformation/iam" - "github.com/awslabs/goformation/v7/cloudformation/lambda" - - "github.com/elastic/beats/v7/libbeat/feature" - "github.com/elastic/beats/v7/libbeat/publisher/pipeline" - "github.com/elastic/beats/v7/x-pack/functionbeat/function/provider" - "github.com/elastic/beats/v7/x-pack/functionbeat/function/telemetry" - "github.com/elastic/beats/v7/x-pack/functionbeat/provider/aws/aws/transformer" - conf "github.com/elastic/elastic-agent-libs/config" - "github.com/elastic/elastic-agent-libs/logp" -) - -type startingPosition uint - -const ( - // Looking at the documentation, Kinesis should also support `AT_TIMESTAMP` but looking at the - // request format for cloudformation, I don't see a way to define the timestamp. - // I've looked at other frameworks, and it seems a bug in the cloudformation API. - // doc: https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-lambda-eventsourcemapping.html - trimHorizonPos startingPosition = iota + 1 - latestPos -) - -var ( - mapStartingPosition = map[string]startingPosition{ - "trim_horizon": trimHorizonPos, - "latest": latestPos, - } - - mapStartingPositionReverse = make(map[startingPosition]string, len(mapStartingPosition)) -) - -func init() { - for k, v := range mapStartingPosition { - mapStartingPositionReverse[v] = strings.ToUpper(k) - } -} - -func (s *startingPosition) Unpack(str string) error { - v, ok := mapStartingPosition[str] - if !ok { - validValues := make([]string, len(mapStartingPosition)) - pos := 0 - for k := range mapStartingPosition { - validValues[pos] = k - pos++ - } - return fmt.Errorf("unknown value %s, valid values are: %s", str, strings.Join(validValues, ", ")) - } - *s = v - return nil -} - -func (s *startingPosition) String() string { - v, ok := mapStartingPositionReverse[*s] - if !ok { - panic("unknown starting position: " + fmt.Sprint(*s)) - } - return v -} - -// KinesisConfig is the configuration for the Kinesis event type. -type KinesisConfig struct { - Description string `config:"description"` - Name string `config:"name" validate:"nonzero,required"` - Triggers []*KinesisTriggerConfig `config:"triggers"` - LambdaConfig *LambdaConfig `config:",inline"` -} - -// Validate validates the configuration. -func (cfg *KinesisConfig) Validate() error { - if len(cfg.Triggers) == 0 { - return errors.New("you need to specify at least one trigger") - } - return nil -} - -// KinesisTriggerConfig configuration for the current trigger. -type KinesisTriggerConfig struct { - EventSourceArn string `config:"event_source_arn" validate:"required"` - BatchSize int `config:"batch_size" validate:"min=100,max=10000"` - StartingPosition startingPosition `config:"starting_position"` - ParallelizationFactor int `config:"parallelization_factor" validate:"min=1,max=10"` -} - -// Unpack unpacks the trigger and make sure the defaults settings are correctly sets. -func (c *KinesisTriggerConfig) Unpack(cfg *conf.C) error { - type tmpConfig KinesisTriggerConfig - config := tmpConfig{ - BatchSize: 100, - StartingPosition: trimHorizonPos, - ParallelizationFactor: 1, - } - if err := cfg.Unpack(&config); err != nil { - return err - } - *c = KinesisTriggerConfig(config) - return nil -} - -// Kinesis receives events from a kinesis stream and forward them to elasticsearch. -type Kinesis struct { - log *logp.Logger - config *KinesisConfig -} - -// NewKinesis creates a new function to receives events from a kinesis stream. -func NewKinesis(provider provider.Provider, cfg *conf.C) (provider.Function, error) { - config := &KinesisConfig{LambdaConfig: DefaultLambdaConfig} - if err := cfg.Unpack(config); err != nil { - return nil, err - } - return &Kinesis{log: logp.NewLogger("kinesis"), config: config}, nil -} - -// KinesisDetails returns the details of the feature. -func KinesisDetails() feature.Details { - return feature.MakeDetails("Kinesis trigger", "receive events from a Kinesis stream", feature.Stable) -} - -// Run starts the lambda function and wait for web triggers. -func (k *Kinesis) Run(_ context.Context, client pipeline.ISyncClient, t telemetry.T) error { - t.AddTriggeredFunction() - - lambdarunner.Start(k.createHandler(client)) - return nil -} - -func (k *Kinesis) createHandler(client pipeline.ISyncClient) func(request events.KinesisEvent) error { - return func(request events.KinesisEvent) error { - k.log.Debugf("The handler receives %d events", len(request.Records)) - - events, err := transformer.KinesisEvent(request) - if err != nil { - return err - } - - if err = client.PublishAll(events); err != nil { - k.log.Errorf("Could not publish events to the pipeline, error: %+v", err) - return err - } - client.Wait() - return nil - } -} - -// Name return the name of the lambda function. -func (k *Kinesis) Name() string { - return "kinesis" -} - -// LambdaConfig returns the configuration to use when creating the lambda. -func (k *Kinesis) LambdaConfig() *LambdaConfig { - return k.config.LambdaConfig -} - -// Template returns the cloudformation template for configuring the service with the specified -// triggers. -func (k *Kinesis) Template() *cloudformation.Template { - template := cloudformation.NewTemplate() - prefix := func(suffix string) string { - return NormalizeResourceName("fnb" + k.config.Name + suffix) - } - - for _, trigger := range k.config.Triggers { - resourceName := prefix(k.Name() + trigger.EventSourceArn) - template.Resources[resourceName] = &lambda.EventSourceMapping{ - BatchSize: cloudformation.Int(trigger.BatchSize), - ParallelizationFactor: cloudformation.Int(trigger.ParallelizationFactor), - EventSourceArn: cloudformation.String(trigger.EventSourceArn), - FunctionName: cloudformation.GetAtt(prefix(""), "Arn"), - StartingPosition: cloudformation.String(trigger.StartingPosition.String()), - } - } - - return template -} - -// Policies returns a slice of policy to add to the lambda role. -func (k *Kinesis) Policies() []iam.Role_Policy { - resources := make([]string, len(k.config.Triggers)) - for idx, trigger := range k.config.Triggers { - resources[idx] = trigger.EventSourceArn - } - - // Give us a chance to generate the same document indenpendant of the changes, - // to help with updates. - sort.Strings(resources) - - policies := []iam.Role_Policy{ - iam.Role_Policy{ - PolicyName: cloudformation.Join("-", []string{"fnb", "kinesis", k.config.Name}), - PolicyDocument: map[string]interface{}{ - "Statement": []map[string]interface{}{ - map[string]interface{}{ - "Action": []string{ - "kinesis:GetRecords", - "kinesis:GetShardIterator", - "Kinesis:DescribeStream", - }, - "Effect": "Allow", - "Resource": resources, - }, - }, - }, - }, - } - - return policies -} diff --git a/x-pack/functionbeat/provider/aws/aws/kinesis_test.go b/x-pack/functionbeat/provider/aws/aws/kinesis_test.go deleted file mode 100644 index 20d92ce36060..000000000000 --- a/x-pack/functionbeat/provider/aws/aws/kinesis_test.go +++ /dev/null @@ -1,302 +0,0 @@ -// Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one -// or more contributor license agreements. Licensed under the Elastic License; -// you may not use this file except in compliance with the Elastic License. - -package aws - -import ( - "crypto/md5" - "errors" - "fmt" - "strconv" - "testing" - - "github.com/aws/aws-lambda-go/events" - "github.com/awslabs/kinesis-aggregation/go/v2/deaggregator" - aggRecProto "github.com/awslabs/kinesis-aggregation/go/v2/records" - "github.com/stretchr/testify/assert" - "google.golang.org/protobuf/proto" - "google.golang.org/protobuf/runtime/protoimpl" - - "github.com/elastic/beats/v7/x-pack/functionbeat/function/provider" - conf "github.com/elastic/elastic-agent-libs/config" -) - -func TestKinesis(t *testing.T) { - cfg := conf.MustNewConfigFrom(map[string]interface{}{ - "name": "foobar", - "triggers": []map[string]interface{}{ - map[string]interface{}{ - "event_source_arn": "abc123", - }, - }, - }) - - t.Run("when publish is successful", func(t *testing.T) { - client := &arrayBackedClient{} - k, err := NewKinesis(&provider.DefaultProvider{}, cfg) - if !assert.NoError(t, err) { - return - } - - c, _ := k.(*Kinesis) - handler := c.createHandler(client) - err = handler(generateKinesisEvent()) - assert.NoError(t, err) - }) - - t.Run("when publish with agg is successful", func(t *testing.T) { - client := &arrayBackedClient{} - k, err := NewKinesis(&provider.DefaultProvider{}, cfg) - if !assert.NoError(t, err) { - return - } - - c, _ := k.(*Kinesis) - handler := c.createHandler(client) - err = handler(generateAggregatedKinesisEvent(true)) - assert.NoError(t, err) - }) - - t.Run("when publish is not successful", func(t *testing.T) { - e := errors.New("something bad") - client := &arrayBackedClient{err: e} - - k, err := NewKinesis(&provider.DefaultProvider{}, cfg) - if !assert.NoError(t, err) { - return - } - - c, _ := k.(*Kinesis) - handler := c.createHandler(client) - err = handler(generateKinesisEvent()) - assert.Equal(t, e, err) - }) - - t.Run("when publish with agg is not successful", func(t *testing.T) { - client := &arrayBackedClient{} - k, err := NewKinesis(&provider.DefaultProvider{}, cfg) - if !assert.NoError(t, err) { - return - } - - c, _ := k.(*Kinesis) - handler := c.createHandler(client) - err = handler(generateAggregatedKinesisEvent(false)) - assert.Error(t, err) - }) - - t.Run("test config validation", testKinesisConfig) - t.Run("test starting position", testStartingPosition) -} - -func generateKinesisEvent() events.KinesisEvent { - return events.KinesisEvent{ - Records: []events.KinesisEventRecord{ - events.KinesisEventRecord{ - AwsRegion: "east-1", - EventID: "1234", - EventName: "connect", - EventSource: "web", - EventSourceArn: "arn:aws:iam::00000000:role/functionbeat", - Kinesis: events.KinesisRecord{ - Data: []byte("hello world"), - PartitionKey: "abc123", - SequenceNumber: "12345", - KinesisSchemaVersion: "v1", - }, - }, - }, - } -} - -func generateAggregatedKinesisEvent(validRec bool) events.KinesisEvent { - // Heavily based on https://github.com/awslabs/kinesis-aggregation/blob/master/go/deaggregator/deaggregator_test.go - aggRec := &aggRecProto.AggregatedRecord{} - unquotedHeader, err := strconv.Unquote(deaggregator.KplMagicHeader) - if err != nil { - panic(err) - } - aggRecBytes := []byte(unquotedHeader) - partKeyTable := make([]string, 0) - partKey := uint64(0) - hashKey := uint64(0) - r := &aggRecProto.Record{ - ExplicitHashKeyIndex: &hashKey, - Data: []byte("hello world"), - Tags: make([]*aggRecProto.Tag, 0), - } - // This seems to be the only way to trigger the deaggregation module to return an error when needed - if validRec { - r.PartitionKeyIndex = &partKey - } - aggRec.Records = append(aggRec.Records, r) - partKeyTable = append(partKeyTable, "0") - - aggRec.PartitionKeyTable = partKeyTable - data, _ := proto.Marshal(protoimpl.X.ProtoMessageV2Of(aggRec)) - md5Hash := md5.Sum(data) - aggRecBytes = append(aggRecBytes, data...) - aggRecBytes = append(aggRecBytes, md5Hash[:]...) - - return events.KinesisEvent{ - Records: []events.KinesisEventRecord{ - { - AwsRegion: "east-1", - EventID: "1234", - EventName: "connect", - EventSource: "web", - EventSourceArn: "arn:aws:iam::00000000:role/functionbeat", - Kinesis: events.KinesisRecord{ - Data: aggRecBytes, - PartitionKey: "abc123", - SequenceNumber: "12345", - KinesisSchemaVersion: "v1", - }, - }, - }, - } -} - -func testKinesisConfig(t *testing.T) { - tests := map[string]struct { - valid bool - rawConfig map[string]interface{} - expected *KinesisConfig - }{ - "minimal valid configuration": { - valid: true, - rawConfig: map[string]interface{}{ - "name": "mysuperfunctionname", - "description": "mylong description", - "triggers": []map[string]interface{}{ - map[string]interface{}{ - "event_source_arn": "mycustomarn", - }, - }, - }, - }, - "missing event triggers": { - valid: false, - rawConfig: map[string]interface{}{ - "name": "mysuperfunctionname", - "description": "mylong description", - }, - }, - "empty or missing event source arn": { - valid: false, - rawConfig: map[string]interface{}{ - "name": "mysuperfunctionname", - "description": "mylong description", - "triggers": []map[string]interface{}{ - map[string]interface{}{ - "event_source_arn": "", - }, - }, - }, - }, - "test upper bound batch size limit": { - valid: false, - rawConfig: map[string]interface{}{ - "name": "mysuperfunctionname", - "description": "mylong description", - "triggers": []map[string]interface{}{ - map[string]interface{}{ - "event_source_arn": "abc123", - "batch_size": 20000, - }, - }, - }, - }, - "test lower bound batch size limit": { - valid: false, - rawConfig: map[string]interface{}{ - "name": "mysuperfunctionname", - "description": "mylong description", - "triggers": []map[string]interface{}{ - map[string]interface{}{ - "event_source_arn": "abc123", - "batch_size": 10, - }, - }, - }, - }, - "test upper bound parallelization factor limit": { - valid: false, - rawConfig: map[string]interface{}{ - "name": "mysuperfunctionname", - "description": "mylong description", - "triggers": []map[string]interface{}{ - map[string]interface{}{ - "event_source_arn": "abc123", - "parallelization_factor": 13, - }, - }, - }, - }, - "test lower bound parallelization factor limit": { - valid: false, - rawConfig: map[string]interface{}{ - "name": "mysuperfunctionname", - "description": "mylong description", - "triggers": []map[string]interface{}{ - map[string]interface{}{ - "event_source_arn": "abc123", - "parallelization_factor": 0, - }, - }, - }, - }, - "test default values": { - valid: true, - rawConfig: map[string]interface{}{ - "name": "mysuperfunctionname", - "description": "mylongdescription", - "triggers": []map[string]interface{}{ - map[string]interface{}{ - "event_source_arn": "abc123", - }, - }, - }, - expected: &KinesisConfig{ - Name: "mysuperfunctionname", - Description: "mylongdescription", - LambdaConfig: DefaultLambdaConfig, - Triggers: []*KinesisTriggerConfig{ - &KinesisTriggerConfig{ - EventSourceArn: "abc123", - BatchSize: 100, - StartingPosition: trimHorizonPos, - ParallelizationFactor: 1, - }, - }, - }, - }, - } - - for name, test := range tests { - t.Run(name, func(t *testing.T) { - cfg := conf.MustNewConfigFrom(test.rawConfig) - config := &KinesisConfig{LambdaConfig: DefaultLambdaConfig} - err := cfg.Unpack(config) - if !assert.Equal(t, test.valid, err == nil, fmt.Sprintf("error: %+v", err)) { - return - } - - if test.expected != nil { - assert.Equal(t, test.expected, config) - } - }) - } -} - -func testStartingPosition(t *testing.T) { - // NOTE(ph) when adding support for at_timestamp we also need to make sure the cloudformation - // template send the timestamp. - // doc: https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-lambda-eventsourcemapping.html - t.Run("AT_TIMESTAMP is not supported yet", func(t *testing.T) { - var s startingPosition - err := s.Unpack("at_timestamp") - assert.Error(t, err) - }) -} diff --git a/x-pack/functionbeat/provider/aws/aws/sqs.go b/x-pack/functionbeat/provider/aws/aws/sqs.go deleted file mode 100644 index adf5f5a16de8..000000000000 --- a/x-pack/functionbeat/provider/aws/aws/sqs.go +++ /dev/null @@ -1,164 +0,0 @@ -// Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one -// or more contributor license agreements. Licensed under the Elastic License; -// you may not use this file except in compliance with the Elastic License. - -package aws - -import ( - "context" - "errors" - "sort" - - "github.com/aws/aws-lambda-go/events" - lambdarunner "github.com/aws/aws-lambda-go/lambda" - "github.com/awslabs/goformation/v7/cloudformation" - "github.com/awslabs/goformation/v7/cloudformation/iam" - "github.com/awslabs/goformation/v7/cloudformation/lambda" - - "github.com/elastic/beats/v7/libbeat/feature" - "github.com/elastic/beats/v7/libbeat/publisher/pipeline" - "github.com/elastic/beats/v7/x-pack/functionbeat/function/provider" - "github.com/elastic/beats/v7/x-pack/functionbeat/function/telemetry" - "github.com/elastic/beats/v7/x-pack/functionbeat/provider/aws/aws/transformer" - conf "github.com/elastic/elastic-agent-libs/config" - "github.com/elastic/elastic-agent-libs/logp" -) - -const batchSize = 10 - -// SQSConfig is the configuration for the SQS event type. -type SQSConfig struct { - Triggers []*SQSTriggerConfig `config:"triggers"` - Description string `config:"description"` - Name string `config:"name" validate:"nonzero,required"` - LambdaConfig *LambdaConfig `config:",inline"` -} - -// SQSTriggerConfig configuration for the current trigger. -type SQSTriggerConfig struct { - EventSourceArn string `config:"event_source_arn"` -} - -// Validate validates the configuration. -func (cfg *SQSConfig) Validate() error { - if len(cfg.Triggers) == 0 { - return errors.New("you need to specify at least one trigger") - } - return nil -} - -// SQS receives events from the web service and forward them to elasticsearch. -type SQS struct { - log *logp.Logger - config *SQSConfig -} - -// NewSQS creates a new function to receives events from a SQS queue. -func NewSQS(provider provider.Provider, cfg *conf.C) (provider.Function, error) { - config := &SQSConfig{LambdaConfig: DefaultLambdaConfig} - if err := cfg.Unpack(config); err != nil { - return nil, err - } - return &SQS{log: logp.NewLogger("sqs"), config: config}, nil -} - -// SQSDetails returns the details of the feature. -func SQSDetails() feature.Details { - return feature.MakeDetails("SQS trigger", "receive events from a SQS queue", feature.Stable) -} - -// Run starts the lambda function and wait for web triggers. -func (s *SQS) Run(_ context.Context, client pipeline.ISyncClient, t telemetry.T) error { - t.AddTriggeredFunction() - - lambdarunner.Start(s.createHandler(client)) - return nil -} - -func (s *SQS) createHandler(client pipeline.ISyncClient) func(request events.SQSEvent) error { - return func(request events.SQSEvent) error { - s.log.Debugf("The handler receives %d events", len(request.Records)) - - events := transformer.SQS(request) - - if err := client.PublishAll(events); err != nil { - s.log.Errorf("Could not publish events to the pipeline, error: %+v", err) - return err - } - client.Wait() - return nil - } -} - -// Name return the name of the lambda function. -func (s *SQS) Name() string { - return "sqs" -} - -// Template returns the cloudformation template for configuring the service with the specified triggers. -func (s *SQS) Template() *cloudformation.Template { - template := cloudformation.NewTemplate() - - prefix := func(suffix string) string { - return NormalizeResourceName("fnb" + s.config.Name + suffix) - } - - for _, trigger := range s.config.Triggers { - resourceName := prefix("SQS") + NormalizeResourceName(trigger.EventSourceArn) - template.Resources[resourceName] = &lambda.EventSourceMapping{ - BatchSize: cloudformation.Int(batchSize), - EventSourceArn: cloudformation.String(trigger.EventSourceArn), - FunctionName: cloudformation.GetAtt(prefix(""), "Arn"), - } - } - return template -} - -// Policies returns a slice of policies to add to the lambda role. -func (s *SQS) Policies() []iam.Role_Policy { - resources := make([]string, len(s.config.Triggers)) - for idx, trigger := range s.config.Triggers { - resources[idx] = trigger.EventSourceArn - } - - // Give us a chance to generate the same document indenpendant of the changes, - // to help with updates. - sort.Strings(resources) - - // SQS Roles permissions: - // - lambda:CreateEventSourceMapping - // - lambda:ListEventSourceMappings - // - lambda:ListFunctions - // - // Lambda Role permission - // - sqs:ChangeMessageVisibility - // - sqs:DeleteMessage - // - sqs:GetQueueAttributes - // - sqs:ReceiveMessage - policies := []iam.Role_Policy{ - iam.Role_Policy{ - PolicyName: cloudformation.Join("-", []string{"fnb", "sqs", s.config.Name}), - PolicyDocument: map[string]interface{}{ - "Statement": []map[string]interface{}{ - map[string]interface{}{ - "Action": []string{ - "sqs:ChangeMessageVisibility", - "sqs:DeleteMessage", - "sqs:GetQueueAttributes", - "sqs:ReceiveMessage", - }, - "Effect": "Allow", - "Resource": resources, - }, - }, - }, - }, - } - - return policies -} - -// LambdaConfig returns the configuration to use when creating the lambda. -func (s *SQS) LambdaConfig() *LambdaConfig { - return s.config.LambdaConfig -} diff --git a/x-pack/functionbeat/provider/aws/aws/sqs_test.go b/x-pack/functionbeat/provider/aws/aws/sqs_test.go deleted file mode 100644 index 88a45cb97930..000000000000 --- a/x-pack/functionbeat/provider/aws/aws/sqs_test.go +++ /dev/null @@ -1,67 +0,0 @@ -// Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one -// or more contributor license agreements. Licensed under the Elastic License; -// you may not use this file except in compliance with the Elastic License. - -package aws - -import ( - "errors" - "testing" - - "github.com/aws/aws-lambda-go/events" - "github.com/stretchr/testify/assert" - - "github.com/elastic/beats/v7/x-pack/functionbeat/function/provider" - conf "github.com/elastic/elastic-agent-libs/config" -) - -func TestSQS(t *testing.T) { - cfg := conf.MustNewConfigFrom(map[string]interface{}{ - "name": "foobar", - "triggers": []map[string]interface{}{ - map[string]interface{}{ - "event_source_arn": "abc1234", - }, - }, - }) - - t.Run("when publish is succesful", func(t *testing.T) { - client := &arrayBackedClient{} - s, err := NewSQS(&provider.DefaultProvider{}, cfg) - if !assert.NoError(t, err) { - return - } - - c, _ := s.(*SQS) - handler := c.createHandler(client) - err = handler(generateSQSEvent()) - assert.NoError(t, err) - }) - - t.Run("when publish is not succesful", func(t *testing.T) { - e := errors.New("something bad") - client := &arrayBackedClient{err: e} - - s, err := NewSQS(&provider.DefaultProvider{}, cfg) - if !assert.NoError(t, err) { - return - } - - c, _ := s.(*SQS) - handler := c.createHandler(client) - err = handler(generateSQSEvent()) - assert.Equal(t, e, err) - }) -} - -func generateSQSEvent() events.SQSEvent { - return events.SQSEvent{ - Records: []events.SQSMessage{ - events.SQSMessage{ - MessageId: "1234", - ReceiptHandle: "12345", - Body: "hello world", - }, - }, - } -} diff --git a/x-pack/functionbeat/provider/aws/aws/transformer/transformer.go b/x-pack/functionbeat/provider/aws/aws/transformer/transformer.go deleted file mode 100644 index 3bf464317a0a..000000000000 --- a/x-pack/functionbeat/provider/aws/aws/transformer/transformer.go +++ /dev/null @@ -1,234 +0,0 @@ -// Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one -// or more contributor license agreements. Licensed under the Elastic License; -// you may not use this file except in compliance with the Elastic License. - -package transformer - -import ( - "bytes" - "compress/gzip" - "encoding/base64" - "encoding/json" - "errors" - "io" - "time" - - "github.com/aws/aws-lambda-go/events" - "github.com/aws/aws-sdk-go-v2/service/kinesis/types" - "github.com/awslabs/kinesis-aggregation/go/v2/deaggregator" - - "github.com/elastic/beats/v7/libbeat/beat" - "github.com/elastic/elastic-agent-libs/mapstr" -) - -// Centralize anything related to ECS into a common file. -// TODO: Look at the fields to align them with ECS. -// TODO: how to keep the fields in sync with AWS? -// TODO: api gateway proxy a lot more information is available. - -// CloudwatchLogs takes an CloudwatchLogsData and transform it into a beat event. -func CloudwatchLogs(request events.CloudwatchLogsData) []beat.Event { - beatEvents := make([]beat.Event, len(request.LogEvents)) - - for idx, logEvent := range request.LogEvents { - beatEvents[idx] = beat.Event{ - Timestamp: time.Unix(0, logEvent.Timestamp*1000000), - Fields: mapstr.M{ - "event": mapstr.M{ - "kind": "event", - }, - "cloud": mapstr.M{ - "provider": "aws", - }, - "message": logEvent.Message, - "id": logEvent.ID, - "owner": request.Owner, - "log_stream": request.LogStream, - "log_group": request.LogGroup, - "message_type": request.MessageType, - "subscription_filters": request.SubscriptionFilters, - }, - } - } - - return beatEvents -} - -// APIGatewayProxyRequest takes a web request on the api gateway proxy and transform it into a beat event. -func APIGatewayProxyRequest(request events.APIGatewayProxyRequest) beat.Event { - return beat.Event{ - Timestamp: time.Now(), - Fields: mapstr.M{ - "event": mapstr.M{ - "kind": "event", - "category": []string{"network"}, - "type": []string{"connection", "protocol"}, - }, - "cloud": mapstr.M{ - "provider": "aws", - "account.id": request.RequestContext.AccountID, - }, - "network": mapstr.M{ - "transport": "tcp", - "protocol": "http", - }, - "resource": request.Resource, - "path": request.Path, - "method": request.HTTPMethod, - "headers": request.Headers, // TODO: ECS map[string] - "query_string": request.QueryStringParameters, // TODO: map[string], might conflict with ECS - "path_parameters": request.PathParameters, - "body": request.Body, // TODO: could be JSON, json processor? could be used by other functions. - "is_base64_encoded": request.IsBase64Encoded, - }, - } -} - -// KinesisEvent takes a kinesis event and create multiples beat events. -// DOCS: https://docs.aws.amazon.com/lambda/latest/dg/with-kinesis.html -func KinesisEvent(request events.KinesisEvent) ([]beat.Event, error) { - var beatEvents []beat.Event - for _, record := range request.Records { - kr := types.Record{ - ApproximateArrivalTimestamp: &record.Kinesis.ApproximateArrivalTimestamp.Time, - Data: record.Kinesis.Data, - EncryptionType: types.EncryptionType(record.Kinesis.EncryptionType), - PartitionKey: &record.Kinesis.PartitionKey, - SequenceNumber: &record.Kinesis.SequenceNumber, - } - deaggRecords, err := deaggregator.DeaggregateRecords([]types.Record{kr}) - if err != nil { - return nil, err - } - - for _, deaggRecord := range deaggRecords { - beatEvents = append(beatEvents, beat.Event{ - Timestamp: *deaggRecord.ApproximateArrivalTimestamp, - Fields: mapstr.M{ - "event": mapstr.M{ - "kind": "event", - }, - "cloud": mapstr.M{ - "provider": "aws", - "region": record.AwsRegion, - }, - "event_id": record.EventID, - "event_name": record.EventName, - "event_source": record.EventSource, - "event_source_arn": record.EventSourceArn, - "event_version": record.EventVersion, - "aws_region": record.AwsRegion, - "message": string(deaggRecord.Data), - "kinesis_partition_key": *deaggRecord.PartitionKey, - "kinesis_schema_version": record.Kinesis.KinesisSchemaVersion, - "kinesis_sequence_number": *deaggRecord.SequenceNumber, - "kinesis_encryption_type": deaggRecord.EncryptionType, - }, - }) - } - } - return beatEvents, nil -} - -// CloudwatchKinesisEvent takes a Kinesis event containing Cloudwatch logs and creates events for all -// Cloudwatch logs. -func CloudwatchKinesisEvent(request events.KinesisEvent, base64Encoded, compressed bool) ([]beat.Event, error) { - var evts []beat.Event - for _, record := range request.Records { - envelopeFields := mapstr.M{ - "event": mapstr.M{ - "kind": "event", - }, - "cloud": mapstr.M{ - "provider": "aws", - "region": record.AwsRegion, - }, - "event_id": record.EventID, - "event_name": record.EventName, - "event_source": record.EventSource, - "event_source_arn": record.EventSourceArn, - "event_version": record.EventVersion, - "aws_region": record.AwsRegion, - "kinesis_partition_key": record.Kinesis.PartitionKey, - "kinesis_schema_version": record.Kinesis.KinesisSchemaVersion, - "kinesis_sequence_number": record.Kinesis.SequenceNumber, - "kinesis_encryption_type": record.Kinesis.EncryptionType, - } - - kinesisData := record.Kinesis.Data - if base64Encoded { - var err error - kinesisData, err = base64.StdEncoding.DecodeString(string(kinesisData)) - if err != nil { - return nil, err - } - } - - if compressed { - inBuf := bytes.NewBuffer(record.Kinesis.Data) - r, err := gzip.NewReader(inBuf) - if err != nil { - return nil, err - } - - var outBuf bytes.Buffer - for { - _, err := io.CopyN(&outBuf, r, 1024) - if err != nil { - if errors.Is(err, io.EOF) { - break - } - _ = r.Close() - return nil, err - } - } - - err = r.Close() - if err != nil { - return nil, err - } - kinesisData = outBuf.Bytes() - } - - var cloudwatchEvents events.CloudwatchLogsData - err := json.Unmarshal(kinesisData, &cloudwatchEvents) - if err != nil { - return nil, err - } - - cwEvts := CloudwatchLogs(cloudwatchEvents) - for _, cwe := range cwEvts { - cwe.Fields.DeepUpdate(envelopeFields) - evts = append(evts, cwe) - } - } - return evts, nil -} - -// SQS takes a SQS event and create multiples beat events. -func SQS(request events.SQSEvent) []beat.Event { - beatEvents := make([]beat.Event, len(request.Records)) - for idx, record := range request.Records { - beatEvents[idx] = beat.Event{ - Timestamp: time.Now(), - Fields: mapstr.M{ - "event": mapstr.M{ - "kind": "event", - }, - "cloud": mapstr.M{ - "provider": "aws", - "region": record.AWSRegion, - }, - "message_id": record.MessageId, - "receipt_handle": record.ReceiptHandle, - "message": record.Body, - "attributes": record.Attributes, - "event_source": record.EventSource, - "event_source_arn": record.EventSourceARN, - "aws_region": record.AWSRegion, - }, - // TODO: SQS message attributes missing, need to check doc - } - } - return beatEvents -} diff --git a/x-pack/functionbeat/provider/aws/aws/transformer/transformer_test.go b/x-pack/functionbeat/provider/aws/aws/transformer/transformer_test.go deleted file mode 100644 index ae0dcb12eee4..000000000000 --- a/x-pack/functionbeat/provider/aws/aws/transformer/transformer_test.go +++ /dev/null @@ -1,403 +0,0 @@ -// Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one -// or more contributor license agreements. Licensed under the Elastic License; -// you may not use this file except in compliance with the Elastic License. - -package transformer - -import ( - "crypto/md5" - "encoding/base64" - "fmt" - "math/rand" - "strconv" - "testing" - "time" - - "github.com/aws/aws-sdk-go-v2/service/kinesis/types" - "google.golang.org/protobuf/runtime/protoimpl" - - "github.com/aws/aws-lambda-go/events" - "github.com/awslabs/kinesis-aggregation/go/v2/deaggregator" - aggRecProto "github.com/awslabs/kinesis-aggregation/go/v2/records" - "github.com/stretchr/testify/assert" - "google.golang.org/protobuf/proto" - - "github.com/elastic/beats/v7/libbeat/beat" - "github.com/elastic/elastic-agent-libs/mapstr" -) - -func TestCloudwatch(t *testing.T) { - logsData := events.CloudwatchLogsData{ - Owner: "me", - LogGroup: "my-group", - LogStream: "stream", - SubscriptionFilters: []string{"MyFilter"}, - MessageType: "DATA_MESSAGE", - LogEvents: []events.CloudwatchLogsLogEvent{ - { - ID: "1234567890123456789", - Timestamp: 1566908691193, - Message: "my interesting message", - }, - }, - } - - events := CloudwatchLogs(logsData) - assert.Equal(t, 1, len(events)) - - expectedTime, err := time.ParseInLocation(time.RFC3339, "2019-08-27T12:24:51.193+00:00", time.UTC) - assert.NoError(t, err) - - expectedEvent := beat.Event{ - Timestamp: expectedTime, - Fields: mapstr.M{ - "event": mapstr.M{ - "kind": "event", - }, - "cloud": mapstr.M{ - "provider": "aws", - }, - "message": "my interesting message", - "id": "1234567890123456789", - "owner": "me", - "log_stream": "stream", - "log_group": "my-group", - "message_type": "DATA_MESSAGE", - "subscription_filters": []string{"MyFilter"}, - }, - } - - assert.Equal(t, expectedEvent.Fields, events[0].Fields) - assert.Equal(t, expectedEvent.Timestamp, events[0].Timestamp.UTC()) -} - -func TestKinesis(t *testing.T) { - t.Run("when kinesis event is successful", func(t *testing.T) { - request := events.KinesisEvent{ - Records: []events.KinesisEventRecord{ - events.KinesisEventRecord{ - AwsRegion: "us-east-1", - EventID: "1234", - EventName: "connect", - EventSource: "web", - EventVersion: "1.0", - EventSourceArn: "arn:aws:iam::00000000:role/functionbeat", - Kinesis: events.KinesisRecord{ - Data: []byte("hello world"), - PartitionKey: "abc123", - SequenceNumber: "12345", - KinesisSchemaVersion: "1.0", - EncryptionType: "test", - }, - }, - }, - } - - events, err := KinesisEvent(request) - assert.NoError(t, err) - assert.Equal(t, 1, len(events)) - - fields := mapstr.M{ - "cloud": mapstr.M{ - "provider": "aws", - "region": "us-east-1", - }, - "event": mapstr.M{ - "kind": "event", - }, - "event_id": "1234", - "event_name": "connect", - "event_source": "web", - "event_source_arn": "arn:aws:iam::00000000:role/functionbeat", - "event_version": "1.0", - "aws_region": "us-east-1", - "message": "hello world", - "kinesis_partition_key": "abc123", - "kinesis_schema_version": "1.0", - "kinesis_sequence_number": "12345", - "kinesis_encryption_type": types.EncryptionType("test"), - } - - assert.Equal(t, fields, events[0].Fields) - }) - - t.Run("when kinesis event with agg is successful", func(t *testing.T) { - rand.Seed(time.Now().UnixNano()) - min, max := 2, 20 - numRecords := rand.Intn(max-min) + min - aggRecBytes := generateKinesisAggregateRecord(numRecords, true) - - request := events.KinesisEvent{ - Records: []events.KinesisEventRecord{ - events.KinesisEventRecord{ - AwsRegion: "us-east-1", - EventID: "1234", - EventName: "connect", - EventSource: "web", - EventVersion: "1.0", - EventSourceArn: "arn:aws:iam::00000000:role/functionbeat", - Kinesis: events.KinesisRecord{ - Data: aggRecBytes, - PartitionKey: "ignored", - SequenceNumber: "12345", - KinesisSchemaVersion: "1.0", - EncryptionType: "test", - }, - }, - }, - } - - events, err := KinesisEvent(request) - assert.NoError(t, err) - assert.Equal(t, numRecords, len(events)) - - envelopeFields := mapstr.M{ - "cloud": mapstr.M{ - "provider": "aws", - "region": "us-east-1", - }, - "event": mapstr.M{ - "kind": "event", - }, - "event_id": "1234", - "event_name": "connect", - "event_source": "web", - "event_source_arn": "arn:aws:iam::00000000:role/functionbeat", - "event_version": "1.0", - "aws_region": "us-east-1", - "kinesis_schema_version": "1.0", - "kinesis_sequence_number": "12345", - "kinesis_encryption_type": types.EncryptionType("test"), - } - - var expectedInnerFields []mapstr.M - for i := 0; i < numRecords; i++ { - expectedInnerFields = append(expectedInnerFields, mapstr.M{ - "message": fmt.Sprintf("%s %d", "hello world", i), - "kinesis_partition_key": fmt.Sprintf("%s %d", "partKey", i), - }) - } - - for i, expectedFields := range expectedInnerFields { - expectedFields.Update(envelopeFields) - assert.Equal(t, expectedFields, events[i].Fields) - } - }) - - t.Run("when kinesis event with agg is not successful", func(t *testing.T) { - aggRecBytes := generateKinesisAggregateRecord(2, false) - - request := events.KinesisEvent{ - Records: []events.KinesisEventRecord{ - events.KinesisEventRecord{ - AwsRegion: "us-east-1", - EventID: "1234", - EventName: "connect", - EventSource: "web", - EventVersion: "1.0", - EventSourceArn: "arn:aws:iam::00000000:role/functionbeat", - Kinesis: events.KinesisRecord{ - Data: aggRecBytes, - PartitionKey: "abc123", - SequenceNumber: "12345", - KinesisSchemaVersion: "1.0", - EncryptionType: "test", - }, - }, - }, - } - - events, err := KinesisEvent(request) - assert.Error(t, err) - assert.Nil(t, events) - }) - - t.Run("when kinesis event with real example agg payload is successful", func(t *testing.T) { - rand.Seed(time.Now().UnixNano()) - numRecords := 10 - aggRecBytes, err := base64.StdEncoding.DecodeString("84mawgoIejJKSjl6dFgaEwgAGg97ImtleSI6InZhbHVlIn0aEwgAGg9" + - "7ImtleSI6InZhbHVlIn0aEwgAGg97ImtleSI6InZhbHVlIn0aEwgAGg97ImtleSI6InZhbHVlIn0aEwgAGg97ImtleSI6InZhbHVlIn" + - "0aEwgAGg97ImtleSI6InZhbHVlIn0aEwgAGg97ImtleSI6InZhbHVlIn0aEwgAGg97ImtleSI6InZhbHVlIn0aEwgAGg97ImtleSI6I" + - "nZhbHVlIn0aEwgAGg97ImtleSI6InZhbHVlIn3xj2DFMGZ0aNQC7aexsnkU") - assert.NoError(t, err) - - request := events.KinesisEvent{ - Records: []events.KinesisEventRecord{ - events.KinesisEventRecord{ - AwsRegion: "us-east-1", - EventID: "1234", - EventName: "connect", - EventSource: "web", - EventVersion: "1.0", - EventSourceArn: "arn:aws:iam::00000000:role/functionbeat", - Kinesis: events.KinesisRecord{ - Data: aggRecBytes, - PartitionKey: "ignored", - SequenceNumber: "12345", - KinesisSchemaVersion: "1.0", - EncryptionType: "test", - }, - }, - }, - } - - events, err := KinesisEvent(request) - assert.NoError(t, err) - assert.Equal(t, numRecords, len(events)) - - envelopeFields := mapstr.M{ - "cloud": mapstr.M{ - "provider": "aws", - "region": "us-east-1", - }, - "event": mapstr.M{ - "kind": "event", - }, - "event_id": "1234", - "event_name": "connect", - "event_source": "web", - "event_source_arn": "arn:aws:iam::00000000:role/functionbeat", - "event_version": "1.0", - "aws_region": "us-east-1", - "kinesis_schema_version": "1.0", - "kinesis_sequence_number": "12345", - "kinesis_encryption_type": types.EncryptionType("test"), - "kinesis_partition_key": "z2JJ9ztX", - "message": `{"key":"value"}`, - } - - for i := 0; i < numRecords; i++ { - assert.Equal(t, envelopeFields, events[i].Fields) - } - }) -} - -func TestCloudwatchKinesis(t *testing.T) { - request := events.KinesisEvent{ - Records: []events.KinesisEventRecord{ - events.KinesisEventRecord{ - AwsRegion: "us-east-1", - EventID: "1234", - EventName: "connect", - EventSource: "web", - EventVersion: "1.0", - EventSourceArn: "arn:aws:iam::00000000:role/functionbeat", - Kinesis: events.KinesisRecord{ - Data: []byte(`eyJtZXNzYWdlVHlwZSI6IkRBVEFfTUVTU0FHRSIsIm93bmVyIjoiMDc5NzA5NzYxMTUyIiwibG9n -R3JvdXAiOiJ0ZXN0ZW0iLCJsb2dTdHJlYW0iOiJmb2x5b21hbnkiLCJzdWJzY3JpcHRpb25GaWx0 -ZXJzIjpbIk1pbmRlbiJdLCJsb2dFdmVudHMiOlt7ImlkIjoiMzQ5MzM1ODk4NzM5NzIwNDAzMDgy -ODAzMDIzMTg1MjMxODU5NjA1NTQxODkxNjg4NzMyNDI2MjQiLCJ0aW1lc3RhbXAiOjE1NjY0NzYz -NDcwMDAsIm1lc3NhZ2UiOiJUZXN0IGV2ZW50IDMifSx7ImlkIjoiMzQ5MzM1ODk4NzM5OTQzNDEw -NTM0Nzg4MzI5NDE2NjQ3MjE2Nzg4MjY4Mzc1MzAzNzkyMjMwNDEiLCJ0aW1lc3RhbXAiOjE1NjY0 -NzYzNDcwMDEsIm1lc3NhZ2UiOiJUZXN0IGV2ZW50IDQifSx7ImlkIjoiMzQ5MzM1ODk4NzQwMTY2 -NDE3OTg2NzczNjM1NjQ4MDYyNTczOTcwOTk0ODU4OTE4ODUyMDM0NTgiLCJ0aW1lc3RhbXAiOjE1 -NjY0NzYzNDcwMDIsIm1lc3NhZ2UiOiJUaGlzIG1lc3NhZ2UgYWxzbyBjb250YWlucyBhbiBFcnJv -ciJ9XX0=`), - PartitionKey: "abc123", - SequenceNumber: "12345", - KinesisSchemaVersion: "1.0", - EncryptionType: "test", - }, - }, - }, - } - - events, err := CloudwatchKinesisEvent(request, true, false) - assert.NoError(t, err) - assert.Equal(t, 3, len(events)) - - envelopeFields := mapstr.M{ - "cloud": mapstr.M{ - "provider": "aws", - "region": "us-east-1", - }, - "event": mapstr.M{ - "kind": "event", - }, - "event_id": "1234", - "event_name": "connect", - "event_source": "web", - "event_source_arn": "arn:aws:iam::00000000:role/functionbeat", - "event_version": "1.0", - "aws_region": "us-east-1", - "kinesis_partition_key": "abc123", - "kinesis_schema_version": "1.0", - "kinesis_sequence_number": "12345", - "kinesis_encryption_type": "test", - } - - expectedInnerFields := []mapstr.M{ - mapstr.M{ - "id": "34933589873972040308280302318523185960554189168873242624", - "log_group": "testem", - "log_stream": "folyomany", - "owner": "079709761152", - "message": "Test event 3", - "message_type": "DATA_MESSAGE", - "subscription_filters": []string{ - "Minden", - }, - }, - mapstr.M{ - "id": "34933589873994341053478832941664721678826837530379223041", - "log_group": "testem", - "log_stream": "folyomany", - "owner": "079709761152", - "message": "Test event 4", - "message_type": "DATA_MESSAGE", - "subscription_filters": []string{ - "Minden", - }, - }, - mapstr.M{ - "id": "34933589874016641798677363564806257397099485891885203458", - "log_group": "testem", - "log_stream": "folyomany", - "owner": "079709761152", - "message": "This message also contains an Error", - "message_type": "DATA_MESSAGE", - "subscription_filters": []string{ - "Minden", - }, - }, - } - - for i, expectedFields := range expectedInnerFields { - expectedFields.Update(envelopeFields) - assert.Equal(t, expectedFields, events[i].Fields) - } -} - -func generateKinesisAggregateRecord(numRecords int, valid bool) []byte { - // Heavily based on https://github.com/awslabs/kinesis-aggregation/blob/master/go/deaggregator/deaggregator_test.go - aggRec := &aggRecProto.AggregatedRecord{} - unquotedHeader, err := strconv.Unquote(deaggregator.KplMagicHeader) - if err != nil { - panic(err) - } - aggRecBytes := []byte(unquotedHeader) - partKeyTable := make([]string, 0) - for i := 0; i < numRecords; i++ { - partKey := uint64(i) - hashKey := uint64(i) - r := &aggRecProto.Record{ - ExplicitHashKeyIndex: &hashKey, - Data: []byte(fmt.Sprintf("%s %d", "hello world", i)), - Tags: make([]*aggRecProto.Tag, 0), - } - // This seems to be the only way to trigger the deaggregation module to return an error when needed - if valid { - r.PartitionKeyIndex = &partKey - } - aggRec.Records = append(aggRec.Records, r) - partKeyTable = append(partKeyTable, fmt.Sprintf("%s %d", "partKey", i)) - } - - aggRec.PartitionKeyTable = partKeyTable - data, _ := proto.Marshal(protoimpl.X.ProtoMessageV2Of(aggRec)) - md5Hash := md5.Sum(data) - aggRecBytes = append(aggRecBytes, data...) - aggRecBytes = append(aggRecBytes, md5Hash[:]...) - - return aggRecBytes -} diff --git a/x-pack/functionbeat/provider/aws/cmd/root.go b/x-pack/functionbeat/provider/aws/cmd/root.go deleted file mode 100644 index c8e7ba17d62b..000000000000 --- a/x-pack/functionbeat/provider/aws/cmd/root.go +++ /dev/null @@ -1,29 +0,0 @@ -// Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one -// or more contributor license agreements. Licensed under the Elastic License; -// you may not use this file except in compliance with the Elastic License. - -package cmd - -import ( - "flag" - - "github.com/elastic/beats/v7/libbeat/cfgfile" - "github.com/elastic/beats/v7/x-pack/functionbeat/function/beater" - funcmd "github.com/elastic/beats/v7/x-pack/functionbeat/function/cmd" -) - -// Name of this beat -var Name = "functionbeat" - -// RootCmd to handle functionbeat -var RootCmd *funcmd.FunctionCmd - -func init() { - RootCmd = funcmd.NewFunctionCmd(Name, beater.New) - RootCmd.PersistentFlags().AddGoFlag(flag.CommandLine.Lookup("d")) - cfgfile.AddAllowedBackwardsCompatibleFlag("d") - RootCmd.PersistentFlags().AddGoFlag(flag.CommandLine.Lookup("v")) - cfgfile.AddAllowedBackwardsCompatibleFlag("v") - RootCmd.PersistentFlags().AddGoFlag(flag.CommandLine.Lookup("e")) - cfgfile.AddAllowedBackwardsCompatibleFlag("e") -} diff --git a/x-pack/functionbeat/provider/aws/include/feature.go b/x-pack/functionbeat/provider/aws/include/feature.go deleted file mode 100644 index 990134484393..000000000000 --- a/x-pack/functionbeat/provider/aws/include/feature.go +++ /dev/null @@ -1,37 +0,0 @@ -// Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one -// or more contributor license agreements. Licensed under the Elastic License; -// you may not use this file except in compliance with the Elastic License. - -package include - -import ( - "github.com/elastic/beats/v7/libbeat/feature" - "github.com/elastic/beats/v7/x-pack/functionbeat/function/provider" - "github.com/elastic/beats/v7/x-pack/functionbeat/provider/aws/aws" -) - -// Bundle exposes the trigger supported by the AWS provider. -var features = provider.Builder( - "aws", - provider.NewDefaultProvider("aws", provider.NewNullCli, provider.NewNullTemplateBuilder), - feature.MakeDetails("AWS Lambda", "listen to events on AWS lambda", feature.Stable), -).AddFunction("cloudwatch_logs", - aws.NewCloudwatchLogs, - aws.CloudwatchLogsDetails(), -).AddFunction("api_gateway_proxy", - aws.NewAPIGatewayProxy, - aws.APIGatewayProxyDetails(), -).AddFunction("kinesis", - aws.NewKinesis, - aws.KinesisDetails(), -).AddFunction("sqs", - aws.NewSQS, - aws.SQSDetails(), -).AddFunction("cloudwatch_logs_kinesis", - aws.NewCloudwatchKinesis, - aws.CloudwatchKinesisDetails(), -).Features() - -func init() { - feature.MustRegister(features...) -} diff --git a/x-pack/functionbeat/provider/aws/main.go b/x-pack/functionbeat/provider/aws/main.go deleted file mode 100644 index 9ee80bb48942..000000000000 --- a/x-pack/functionbeat/provider/aws/main.go +++ /dev/null @@ -1,18 +0,0 @@ -// Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one -// or more contributor license agreements. Licensed under the Elastic License; -// you may not use this file except in compliance with the Elastic License. - -package main - -import ( - "os" - - "github.com/elastic/beats/v7/x-pack/functionbeat/provider/aws/cmd" - _ "github.com/elastic/beats/v7/x-pack/functionbeat/provider/aws/include" -) - -func main() { - if err := cmd.RootCmd.Execute(); err != nil { - os.Exit(1) - } -} diff --git a/x-pack/functionbeat/provider/aws/main_test.go b/x-pack/functionbeat/provider/aws/main_test.go deleted file mode 100644 index f180fd28275d..000000000000 --- a/x-pack/functionbeat/provider/aws/main_test.go +++ /dev/null @@ -1,35 +0,0 @@ -// Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one -// or more contributor license agreements. Licensed under the Elastic License; -// you may not use this file except in compliance with the Elastic License. - -package main - -// This file is mandatory as otherwise the functionbeat.test binary is not generated correctly. - -import ( - "flag" - "testing" - - "github.com/elastic/beats/v7/libbeat/cfgfile" - "github.com/elastic/beats/v7/x-pack/functionbeat/provider/aws/cmd" -) - -var systemTest *bool - -func init() { - testing.Init() - systemTest = flag.Bool("systemTest", false, "Set to true when running system tests") - - cmd.RootCmd.PersistentFlags().AddGoFlag(flag.CommandLine.Lookup("systemTest")) - cfgfile.AddAllowedBackwardsCompatibleFlag("systemTest") - cmd.RootCmd.PersistentFlags().AddGoFlag(flag.CommandLine.Lookup("test.coverprofile")) - cfgfile.AddAllowedBackwardsCompatibleFlag("test.coverprofile") -} - -// Test started when the test binary is started. Only calls main. -func TestSystem(t *testing.T) { - cfgfile.ConvertFlagsForBackwardsCompatibility() - if *systemTest { - main() - } -} diff --git a/x-pack/functionbeat/provider/local/cmd/root.go b/x-pack/functionbeat/provider/local/cmd/root.go deleted file mode 100644 index 11307a141b19..000000000000 --- a/x-pack/functionbeat/provider/local/cmd/root.go +++ /dev/null @@ -1,20 +0,0 @@ -// Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one -// or more contributor license agreements. Licensed under the Elastic License; -// you may not use this file except in compliance with the Elastic License. - -package cmd - -import ( - funcmd "github.com/elastic/beats/v7/x-pack/functionbeat/function/cmd" - "github.com/elastic/beats/v7/x-pack/functionbeat/manager/beater" -) - -// Name of this beat -var Name = "functionbeat" - -// RootCmd to handle functionbeat -var RootCmd *funcmd.FunctionCmd - -func init() { - RootCmd = funcmd.NewFunctionCmd(Name, beater.New) -} diff --git a/x-pack/functionbeat/provider/local/include/feature.go b/x-pack/functionbeat/provider/local/include/feature.go deleted file mode 100644 index d5eed566826a..000000000000 --- a/x-pack/functionbeat/provider/local/include/feature.go +++ /dev/null @@ -1,14 +0,0 @@ -// Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one -// or more contributor license agreements. Licensed under the Elastic License; -// you may not use this file except in compliance with the Elastic License. - -package include - -import ( - "github.com/elastic/beats/v7/libbeat/feature" - "github.com/elastic/beats/v7/x-pack/functionbeat/provider/local/local" -) - -func init() { - feature.MustRegister(local.Features...) -} diff --git a/x-pack/functionbeat/provider/local/local/local.go b/x-pack/functionbeat/provider/local/local/local.go deleted file mode 100644 index 76edf380846c..000000000000 --- a/x-pack/functionbeat/provider/local/local/local.go +++ /dev/null @@ -1,103 +0,0 @@ -// Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one -// or more contributor license agreements. Licensed under the Elastic License; -// you may not use this file except in compliance with the Elastic License. - -package local - -import ( - "bufio" - "context" - "os" - "time" - - "github.com/elastic/beats/v7/libbeat/beat" - "github.com/elastic/beats/v7/libbeat/feature" - "github.com/elastic/beats/v7/libbeat/publisher/pipeline" - "github.com/elastic/beats/v7/x-pack/functionbeat/function/provider" - "github.com/elastic/beats/v7/x-pack/functionbeat/function/telemetry" - conf "github.com/elastic/elastic-agent-libs/config" - "github.com/elastic/elastic-agent-libs/mapstr" -) - -const stdinName = "stdin" - -// Features exposes the local provider and the STDIN function. -var Features = provider.Builder( - "local", - provider.NewDefaultProvider("local", provider.NewNullCli, provider.NewNullTemplateBuilder), - feature.MakeDetails("local events", "allows to trigger events locally.", feature.Experimental), -).AddFunction( - stdinName, - NewStdinFunction, - feature.MakeDetails(stdinName, "read events from stdin", feature.Experimental), -).Features() - -// StdinFunction reads events from STIN and terminates when stdin is completed. -type StdinFunction struct{} - -// NewStdinFunction creates a new StdinFunction -func NewStdinFunction( - provider provider.Provider, - functionConfig *conf.C, -) (provider.Function, error) { - return &StdinFunction{}, nil -} - -// Run reads events from the STDIN and send them to the publisher pipeline, will stop reading by -// either by an external signal to stop or by reaching EOF. When EOF is reached functionbeat will shutdown. -func (s *StdinFunction) Run(ctx context.Context, client pipeline.ISyncClient, _ telemetry.T) error { - errChan := make(chan error) - defer close(errChan) - lineChan := make(chan string) - defer close(lineChan) - - // Make the os.Stdin interruptable, the shutdown cleanup will unblock the os.Stdin and the goroutine. - go func(ctx context.Context, lineChan chan string, errChan chan error) { - buf := bufio.NewReader(os.Stdin) - scanner := bufio.NewScanner(buf) - scanner.Split(bufio.ScanLines) - - for scanner.Scan() { - if err := scanner.Err(); err != nil { - errChan <- err - return - } - - select { - case <-ctx.Done(): - return - case lineChan <- scanner.Text(): - } - } - }(ctx, lineChan, errChan) - - for { - select { - case <-ctx.Done(): - return os.Stdin.Close() - case err := <-errChan: - return err - case line := <-lineChan: - event := s.newEvent(line) - err := client.Publish(event) - if err != nil { - return err - } - } - } -} - -func (s *StdinFunction) newEvent(line string) beat.Event { - event := beat.Event{ - Timestamp: time.Now(), - Fields: mapstr.M{ - "message": line, - }, - } - return event -} - -// Name returns the name of the stdin function. -func (s *StdinFunction) Name() string { - return stdinName -} diff --git a/x-pack/functionbeat/provider/local/main.go b/x-pack/functionbeat/provider/local/main.go deleted file mode 100644 index 35284d4a716f..000000000000 --- a/x-pack/functionbeat/provider/local/main.go +++ /dev/null @@ -1,18 +0,0 @@ -// Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one -// or more contributor license agreements. Licensed under the Elastic License; -// you may not use this file except in compliance with the Elastic License. - -package main - -import ( - "os" - - "github.com/elastic/beats/v7/x-pack/functionbeat/provider/local/cmd" - _ "github.com/elastic/beats/v7/x-pack/functionbeat/provider/local/include" // imports features -) - -func main() { - if err := cmd.RootCmd.Execute(); err != nil { - os.Exit(1) - } -} diff --git a/x-pack/functionbeat/provider/local/main_test.go b/x-pack/functionbeat/provider/local/main_test.go deleted file mode 100644 index 7c617b300a65..000000000000 --- a/x-pack/functionbeat/provider/local/main_test.go +++ /dev/null @@ -1,35 +0,0 @@ -// Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one -// or more contributor license agreements. Licensed under the Elastic License; -// you may not use this file except in compliance with the Elastic License. - -package main - -// This file is mandatory as otherwise the functionbeat.test binary is not generated correctly. - -import ( - "flag" - "testing" - - "github.com/elastic/beats/v7/libbeat/cfgfile" - "github.com/elastic/beats/v7/x-pack/functionbeat/provider/local/cmd" -) - -var systemTest *bool - -func init() { - testing.Init() - systemTest = flag.Bool("systemTest", false, "Set to true when running system tests") - - cmd.RootCmd.PersistentFlags().AddGoFlag(flag.CommandLine.Lookup("systemTest")) - cfgfile.AddAllowedBackwardsCompatibleFlag("systemTest") - cmd.RootCmd.PersistentFlags().AddGoFlag(flag.CommandLine.Lookup("test.coverprofile")) - cfgfile.AddAllowedBackwardsCompatibleFlag("test.coverprofile") -} - -// Test started when the test binary is started. Only calls main. -func TestSystem(t *testing.T) { - cfgfile.ConvertFlagsForBackwardsCompatibility() - if *systemTest { - main() - } -} diff --git a/x-pack/functionbeat/scripts/mage/config.go b/x-pack/functionbeat/scripts/mage/config.go deleted file mode 100644 index 1d3e773d602f..000000000000 --- a/x-pack/functionbeat/scripts/mage/config.go +++ /dev/null @@ -1,23 +0,0 @@ -// Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one -// or more contributor license agreements. Licensed under the Elastic License; -// you may not use this file except in compliance with the Elastic License. - -package mage - -import ( - devtools "github.com/elastic/beats/v7/dev-tools/mage" -) - -// XPackConfigFileParams returns the configuration of sample and reference configuration data. -func XPackConfigFileParams() devtools.ConfigFileParams { - p := devtools.DefaultConfigFileParams() - p.Templates = append(p.Templates, "_meta/config/*.tmpl") - p.ExtraVars = map[string]interface{}{ - "ExcludeConsole": false, - "ExcludeFileOutput": true, - "ExcludeKafka": true, - "ExcludeRedis": true, - "UseDockerMetadataProcessor": false, - } - return p -} diff --git a/x-pack/functionbeat/scripts/mage/providers.go b/x-pack/functionbeat/scripts/mage/providers.go deleted file mode 100644 index d77c1da548df..000000000000 --- a/x-pack/functionbeat/scripts/mage/providers.go +++ /dev/null @@ -1,55 +0,0 @@ -// Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one -// or more contributor license agreements. Licensed under the Elastic License; -// you may not use this file except in compliance with the Elastic License. - -package mage - -import ( - "fmt" - "os" - "strings" -) - -var ( - availableProviders = []ProviderDetails{ - {Name: "aws", Buildable: true, GOOS: "linux", GOARCH: "amd64"}, - } -) - -// ProviderDetails stores information about the available cloud providers. -type ProviderDetails struct { - Name string - Buildable bool - GOOS string - GOARCH string -} - -// SelectedProviders is the list of selected providers -// Can be configured by setting PROVIDERS enviroment variable. -func SelectedProviders() ([]ProviderDetails, error) { - providers := os.Getenv("PROVIDERS") - if len(providers) == 0 { - return availableProviders, nil - } - - names := strings.Split(providers, ",") - providerDetails := make([]ProviderDetails, len(names)) - for i, name := range names { - p, err := findProviderDetails(name) - if err != nil { - return nil, err - } - providerDetails[i] = p - } - return providerDetails, nil -} - -func findProviderDetails(name string) (ProviderDetails, error) { - for _, p := range availableProviders { - if p.Name == name { - return p, nil - } - } - - return ProviderDetails{}, fmt.Errorf("no such provider") -} diff --git a/x-pack/functionbeat/scripts/mage/update.go b/x-pack/functionbeat/scripts/mage/update.go deleted file mode 100644 index 468bdafbe0fd..000000000000 --- a/x-pack/functionbeat/scripts/mage/update.go +++ /dev/null @@ -1,48 +0,0 @@ -// Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one -// or more contributor license agreements. Licensed under the Elastic License; -// you may not use this file except in compliance with the Elastic License. - -package mage - -import ( - "github.com/magefile/mage/mg" - - devtools "github.com/elastic/beats/v7/dev-tools/mage" -) - -// Update target namespace. -type Update mg.Namespace - -// Aliases stores aliases for the targets. -var Aliases = map[string]interface{}{ - "update": Update.All, -} - -// All updates all generated content. -func (Update) All() { - mg.Deps(Update.Fields, Update.IncludeFields, Update.Config, Update.FieldDocs) -} - -// Config generates both the short and reference configs. -func (Update) Config() error { - return devtools.Config(devtools.ShortConfigType|devtools.ReferenceConfigType, XPackConfigFileParams(), ".") -} - -// Fields generates a fields.yml for the Beat. -func (Update) Fields() error { - return devtools.GenerateFieldsYAML() -} - -// FieldDocs collects all fields by provider and generates documentation for them. -func (Update) FieldDocs() error { - mg.Deps(Update.Fields) - - return devtools.Docs.FieldDocs("fields.yml") -} - -// IncludeFields generates include/fields.go by provider. -func (Update) IncludeFields() error { - mg.Deps(Update.Fields) - - return devtools.GenerateAllInOneFieldsGo() -} diff --git a/x-pack/functionbeat/tests/system/config/functionbeat.yml.j2 b/x-pack/functionbeat/tests/system/config/functionbeat.yml.j2 deleted file mode 100644 index 64a69bceab97..000000000000 --- a/x-pack/functionbeat/tests/system/config/functionbeat.yml.j2 +++ /dev/null @@ -1,101 +0,0 @@ -################### Beat Configuration ######################### -{% if local %} -functionbeat.provider.local: - functions: - - type: stdin - enabled: true -{% endif %} - -{% if cloudwatch %} -functionbeat.provider.aws.endpoint: {{ cloudwatch.endpoint | default("s3.amazonaws.com") }} -functionbeat.provider.aws.deploy_bucket: {{ cloudwatch.bucket | default("functionbeat-deploy") }} -functionbeat.provider.aws.functions: - - name: {{ cloudwatch.name }} - enabled: true - type: cloudwatch_logs - description: "lambda function for cloudwatch logs" - {% if cloudwatch.role %}role: {{ cloudwatch.role }}{% endif %} - {% if cloudwatch.virtual_private_cloud %} - virtual_private_cloud: - security_group_ids: {{ cloudwatch.virtual_private_cloud.security_group_ids }} - subnet_ids: {{ cloudwatch.virtual_private_cloud.subnet_ids }} - {% endif %} - - triggers: - - log_group_name: {{ cloudwatch.log_group | default("/aws/lambda/functionbeat-cloudwatch") }} -{% endif %} - -############################# Output ########################################## - -# Configure what outputs to use when sending the data collected by the beat. -# You can enable one or multiple outputs by setting enabled option to true. -output: - - ### File as output - file: - # Enabling file output - enabled: true - - # Path to the directory where to save the generated files. The option is mandatory. - path: {{ output_file_path|default(beat.working_dir + "/output") }} - - - # Name of the generated files. The default is `functionbeat` and it generates - # files: `functionbeat`, `functionbeat.1`, `functionbeat.2`, etc. - filename: {{ output_file_filename|default("functionbeat") }} - - # Maximum size in kilobytes of each file. When this size is reached, the files are - # rotated. The default value is 10 MB. - #rotate_every_kb: 10000 - - # Maximum number of files under path. When this number of files is reached, the - # oldest file is deleted and the rest are shifted from last to first. The default - # is 7 files. - #number_of_files: 7 - - - -############################# Beat ######################################### - -# The name of the shipper that publishes the network data. It can be used to group -# all the transactions sent by a single shipper in the web interface. -# If this options is not defined, the hostname is used. -#name: - -# The tags of the shipper are included in their own field with each -# transaction published. Tags make it easy to group servers by different -# logical properties. -#tags: ["service-X", "web-tier"] - - - -############################# Logging ######################################### - -#logging: - # Send all logging output to syslog. On Windows default is false, otherwise - # default is true. - #to_syslog: true - - # Write all logging output to files. Beats automatically rotate files if configurable - # limit is reached. - #to_files: false - - # Enable debug output for selected components. - #selectors: [] - - # Set log level - #level: error - - #files: - # The directory where the log files will written to. - #path: /var/log/functionbeat - - # The name of the files where the logs are written to. - #name: functionbeat - - # Configure log file size limit. If limit is reached, log file will be - # automatically rotated - #rotateeverybytes: 10485760 # = 10MB - - # Number of rotated log files to keep. Oldest files will be deleted first. - #keepfiles: 7 diff --git a/x-pack/functionbeat/tests/system/functionbeat.py b/x-pack/functionbeat/tests/system/functionbeat.py deleted file mode 100644 index 24327363aefc..000000000000 --- a/x-pack/functionbeat/tests/system/functionbeat.py +++ /dev/null @@ -1,12 +0,0 @@ -import os -import sys -from beat.beat import TestCase - - -class BaseTest(TestCase): - - @classmethod - def setUpClass(self): - self.beat_name = "functionbeat" - self.beat_path = os.path.abspath(os.path.join(os.path.dirname(__file__), "../../")) - super(BaseTest, self).setUpClass() diff --git a/x-pack/functionbeat/tests/system/requirements.txt b/x-pack/functionbeat/tests/system/requirements.txt deleted file mode 100644 index c2399b66f80b..000000000000 --- a/x-pack/functionbeat/tests/system/requirements.txt +++ /dev/null @@ -1 +0,0 @@ -protobuf==3.19.5 #Temporary change because of protobuf new version bug: https://github.com/protocolbuffers/protobuf/issues/10051 diff --git a/x-pack/functionbeat/tests/system/test_base.py b/x-pack/functionbeat/tests/system/test_base.py deleted file mode 100644 index 39a1051f8061..000000000000 --- a/x-pack/functionbeat/tests/system/test_base.py +++ /dev/null @@ -1,118 +0,0 @@ -from functionbeat import BaseTest - -import json -import os -import unittest -from beat import common_tests - - -class Test(BaseTest, common_tests.TestExportsMixin): - @unittest.skip("temporarily disabled") - def test_base(self): - """ - Basic test with exiting Functionbeat normally - """ - self.render_config_template( - path=os.path.abspath(self.working_dir) + "/log/*", - local=True, - ) - - functionbeat_proc = self.start_beat() - self.wait_until(lambda: self.log_contains("functionbeat is running")) - exit_code = functionbeat_proc.kill_and_wait() - assert exit_code == 0 - - def test_export_function(self): - """ - Test if the template can be exported - """ - - function_name = "testcloudwatchlogs" - bucket_name = "my-bucket-name" - fnb_name = "fnb" + function_name - role = "arn:aws:iam::123456789012:role/MyFunction" - security_group_ids = ["sg-ABCDEFGHIJKL"] - subnet_ids = ["subnet-ABCDEFGHIJKL"] - log_group = "/aws/lambda/functionbeat-cloudwatch" - - self._generate_dummy_binary_for_template_checksum() - - self.render_config_template( - path=os.path.abspath(self.working_dir) + "/log/*", - cloudwatch={ - "name": function_name, - "bucket": bucket_name, - "role": role, - "virtual_private_cloud": { - "security_group_ids": security_group_ids, - "subnet_ids": subnet_ids, - }, - "log_group": log_group, - }, - ) - functionbeat_proc = self.start_beat( - logging_args=["-d", "*"], - extra_args=["export", "function", function_name] - ) - - self.wait_until(lambda: self.log_contains("PASS")) - functionbeat_proc.check_wait() - - function_template = self._get_generated_function_template() - function_properties = function_template["Resources"][fnb_name]["Properties"] - - assert function_properties["FunctionName"] == function_name - assert function_properties["Code"]["S3Bucket"] == bucket_name - assert function_properties["Role"] == role - assert function_properties["VpcConfig"]["SecurityGroupIds"] == security_group_ids - assert function_properties["VpcConfig"]["SubnetIds"] == subnet_ids - - def test_export_function_invalid_conf(self): - """ - Test if invalid configuration is exportable - """ - function_name = "INVALID_$_FUNCTION_$_NAME" - bucket_name = "my-bucket-name" - - self._generate_dummy_binary_for_template_checksum() - - self.render_config_template( - path=os.path.abspath(self.working_dir) + "/log/*", - cloudwatch={ - "name": function_name, - "bucket": bucket_name, - }, - ) - functionbeat_proc = self.start_beat( - logging_args=["-d", "*"], - extra_args=["export", "function", function_name] - ) - - self.wait_until( - lambda: self.log_contains("error while finding enabled functions: invalid name: '{}'".format(function_name)) - ) - - exit_code = functionbeat_proc.kill_and_wait() - assert exit_code != 0 - - def _generate_dummy_binary_for_template_checksum(self): - fnbeat_pkg = os.path.join("pkg", "functionbeat") - fnbeat_aws_pkg = os.path.join("pkg", "functionbeat-aws") - bins_to_gen = [fnbeat_pkg, fnbeat_aws_pkg] - - if not os.path.exists("pkg"): - os.mkdir("pkg") - - for fb in bins_to_gen: - if os.path.exists(fb): - continue - with open(fb, "w") as f: - f.write("my dummy functionbeat binary\n") - - def _get_generated_function_template(self): - log = self.get_log() - # Trim the extra output from the Go test wrapper (like PASS/FAIL and - # coverage information). - log = log[:log.rindex('}') + 1] - function_template = json.loads(log) - return function_template diff --git a/x-pack/libbeat/docs/aws-credentials-config.asciidoc b/x-pack/libbeat/docs/aws-credentials-config.asciidoc index 423e241f8963..451980c28b7d 100644 --- a/x-pack/libbeat/docs/aws-credentials-config.asciidoc +++ b/x-pack/libbeat/docs/aws-credentials-config.asciidoc @@ -120,10 +120,6 @@ ifeval::["{beatname_lc}"=="metricbeat"] include::../../../metricbeat/docs/aws-credentials-examples.asciidoc[] endif::[] -ifeval::["{beatname_lc}"=="functionbeat"] -include::../../../filebeat/docs/aws-credentials-examples.asciidoc[] -endif::[] - [float] ==== AWS Credentials Types There are two different types of AWS credentials can be used: From 8ec2e315b1c0c2ef200b018c11bf21f12b6a4b3f Mon Sep 17 00:00:00 2001 From: Christiano Haesbaert Date: Wed, 11 Dec 2024 17:04:02 +0100 Subject: [PATCH 38/48] auditbeat: Add a cached file hasher for auditbeat (#41952) This implements a LRU cache on top of the FileHasher from hasher.go, it will be used in the new backend for the system process module on linux. The cache is indexed by file path and stores the metadata (what we get from stat(2)/statx(2)) along with the hashes of each file. When we want to hash a file: we stat() the file, then do cache lookup and compare against the stored metadata, if it differs, we rehash, if not we use the cached values. The cache ignores access time (atime), it's only interested in write modifications, if the machine doesn't support statx(2) it falls back to stat(2) but uses the same Unix.Statx_t. With this we end up with a stat() + lookup on the hotpath, and a stat() + stat() + insert on the cold path. The motivation for this is that the new backend ends up fetching "all processes", which in turn causes it to try to hash at every event, the current/old hasher just can't cope with it: 1. Hashing for each event is simply to expensive, in the 100us-50ms range on the default configuration, which puts us below 1000/s. 2. It has a scan rate throttling that on the default configuration ends easily at 40ms per event (25/s). With the cache things improve considerably, we stay below 5us (200k/s) in all cases: ``` MISSES "miss (/usr/sbin/sshd) took 2.571359ms" "miss (/usr/bin/containerd) took 52.099386ms" "miss (/usr/sbin/gssproxy) took 160us" "miss (/usr/sbin/atd) took 50.032us" HITS "hit (/usr/sbin/sshd) took 2.163us" "hit (/usr/lib/systemd/systemd) took 3.024us" "hit (/usr/lib/systemd/systemd) took 859ns" "hit (/usr/sbin/sshd) took 805ns" ``` --- CHANGELOG.next.asciidoc | 1 + auditbeat/helper/hasher/cached_hasher.go | 221 ++++++++++++++++++ auditbeat/helper/hasher/cached_hasher_test.go | 151 ++++++++++++ 3 files changed, 373 insertions(+) create mode 100644 auditbeat/helper/hasher/cached_hasher.go create mode 100644 auditbeat/helper/hasher/cached_hasher_test.go diff --git a/CHANGELOG.next.asciidoc b/CHANGELOG.next.asciidoc index 79eb7b66e59d..ae41114ae53b 100644 --- a/CHANGELOG.next.asciidoc +++ b/CHANGELOG.next.asciidoc @@ -127,6 +127,7 @@ https://github.com/elastic/beats/compare/v8.8.1\...main[Check the HEAD diff] - auditd: Use ECS `event.type: end` instead of `stop` for SERVICE_STOP, DAEMON_ABORT, and DAEMON_END messages. {pull}41558[41558] - auditd: Update syscall names for Linux 6.11. {pull}41558[41558] - hasher: Geneneral improvements and fixes. {pull}41863[41863] +- hasher: Add a cached hasher for upcoming backend. {pull}41952[41952] *Filebeat* diff --git a/auditbeat/helper/hasher/cached_hasher.go b/auditbeat/helper/hasher/cached_hasher.go new file mode 100644 index 000000000000..0af7bb01c74d --- /dev/null +++ b/auditbeat/helper/hasher/cached_hasher.go @@ -0,0 +1,221 @@ +// Licensed to Elasticsearch B.V. under one or more contributor +// license agreements. See the NOTICE file distributed with +// this work for additional information regarding copyright +// ownership. Elasticsearch B.V. licenses this file to you under +// the Apache License, Version 2.0 (the "License"); you may +// not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, +// software distributed under the License is distributed on an +// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +// KIND, either express or implied. See the License for the +// specific language governing permissions and limitations +// under the License. + +//go:build linux + +package hasher + +import ( + "errors" + "time" + + lru "github.com/hashicorp/golang-lru/v2" + "golang.org/x/sys/unix" + + "github.com/elastic/elastic-agent-libs/logp" +) + +// CachedHasher is a metadata aware FileHasher with a LRU cache on top of it. +type CachedHasher struct { + hasher *FileHasher + hashLRU *lru.Cache[string, hashEntry] + hasStatx bool + stats CachedHasherStats + log *logp.Logger +} + +// CachedHasherStats are basics statistics for debugging and testing. +type CachedHasherStats struct { + Hits uint64 + Misses uint64 + Invalidations uint64 + Evictions uint64 +} + +// hashEntry is an entry in the LRU cache. +type hashEntry struct { + statx unix.Statx_t + hashes map[HashType]Digest +} + +// NewFileHasherWithCache creates a CachedHasher with space up to size elements. +func NewFileHasherWithCache(c Config, size int) (*CachedHasher, error) { + // We don't rate limit our hashes, we cache + c.ScanRateBytesPerSec = 0 + hasher, err := NewFileHasher(c, nil) + if err != nil { + return nil, err + } + hashLRU, err := lru.New[string, hashEntry](size) + if err != nil { + return nil, err + } + var nada unix.Statx_t + hasStatx := unix.Statx(-1, "/", 0, unix.STATX_ALL|unix.STATX_MNT_ID, &nada) != unix.ENOSYS + + return &CachedHasher{ + hasher: hasher, + hashLRU: hashLRU, + hasStatx: hasStatx, + log: logp.NewLogger("cached_hasher"), + }, nil +} + +// HashFile looks up a hashEntry in the cache, if the lookup fails, +// the hash is computed, inserted in the cache, and returned. If the +// lookup succeeds but the file metadata changed, the entry is evicted +// and refreshed. +func (ch *CachedHasher) HashFile(path string) (map[HashType]Digest, error) { + var x time.Time + if logp.IsDebug("cached_hasher") { + x = time.Now() + } + + // See if we have it stored + if entry, ok := ch.hashLRU.Get(path); ok { + statx, err := ch.statxFromPath(path) + if err != nil { + // No point in keeping an entry if we can't compare + if !ch.hashLRU.Remove(path) { + err := errors.New("can't remove existing entry, this is a bug") + ch.log.Error(err) + } + return nil, err + } + // If metadata didn't change, this is a good entry, if not fall and rehash + if statx == entry.statx { + ch.log.Debugf("hit (%s) took %v", path, time.Since(x)) + ch.stats.Hits++ + return entry.hashes, nil + } + // Zap from lru + if !ch.hashLRU.Remove(path) { + err := errors.New("can't remove existing entry, this is a bug") + ch.log.Error(err) + return nil, err + } else { + ch.stats.Invalidations++ + ch.log.Debugf("invalidate (%s)", path) + } + } + // Nah, so do the hard work + hashes, err := ch.hasher.HashFile(path) + if err != nil { + return nil, err + } + // Fetch metadata + statx, err := ch.statxFromPath(path) + if err != nil { + return nil, err + } + // Insert + entry := hashEntry{hashes: hashes, statx: statx} + if ch.hashLRU.Add(path, entry) { + ch.stats.Evictions++ + ch.log.Debugf("evict (%s)") + } + + ch.log.Debugf("miss (%s) took %v", path, time.Since(x)) + ch.stats.Misses++ + + return entry.hashes, nil +} + +// Close releases all resources +func (ch *CachedHasher) Close() { + ch.hashLRU.Purge() +} + +// Stats returns basic stats suitable for debugging and testing +func (ch *CachedHasher) Stats() CachedHasherStats { + return ch.stats +} + +// statxFromPath returns the metadata (unix.Statx_t) of path. In case +// the system doesn't support statx(2), it uses stat(2) and fills the +// corresponding members of unix.Statx_t, leaving the remaining members +// with a zero value. +func (ch *CachedHasher) statxFromPath(path string) (unix.Statx_t, error) { + if ch.hasStatx { + var tmpstx unix.Statx_t + err := unix.Statx(-1, path, 0, unix.STATX_ALL|unix.STATX_MNT_ID, &tmpstx) + if err != nil { + return unix.Statx_t{}, err + } + + // This might look stupid, but it guarantees we only compare + // the members we are really interested, unix.Statx_t grows + // with time, so if they ever add a member that changes all + // the time, we don't introduce a bug where we compare things + // we don't want to. + return unix.Statx_t{ + Mask: tmpstx.Mask, + Blksize: tmpstx.Blksize, + Attributes: tmpstx.Attributes, + Nlink: tmpstx.Nlink, + Uid: tmpstx.Uid, + Gid: tmpstx.Gid, + Mode: tmpstx.Mode, + Ino: tmpstx.Ino, + Size: tmpstx.Size, + Blocks: tmpstx.Blocks, + Attributes_mask: tmpstx.Attributes_mask, + Btime: tmpstx.Btime, + Ctime: tmpstx.Ctime, + Mtime: tmpstx.Mtime, + Rdev_minor: tmpstx.Rdev_minor, + Rdev_major: tmpstx.Rdev_major, + // no Atime + // no Dio_mem_align + // no Dio_offset_align + // no Subvol + // no Atomic_write_unit_min + // no Atomic_write_unit_max + // no Atomic_write_segments_max + }, nil + } + + // No statx(2), fallback to stat(2) + var st unix.Stat_t + if err := unix.Stat(path, &st); err != nil { + return unix.Statx_t{}, err + } + + return unix.Statx_t{ + Dev_major: unix.Major(st.Dev), + Dev_minor: unix.Minor(st.Dev), + Ino: st.Ino, + Nlink: uint32(st.Nlink), + Mode: uint16(st.Mode), + Uid: st.Uid, + Gid: st.Gid, + Rdev_major: unix.Major(st.Rdev), + Rdev_minor: unix.Minor(st.Rdev), + Size: uint64(st.Size), + Blksize: uint32(st.Blksize), + Blocks: uint64(st.Blocks), + Mtime: unix.StatxTimestamp{ + Nsec: uint32(st.Mtim.Nsec), + Sec: st.Mtim.Sec, + }, + Ctime: unix.StatxTimestamp{ + Nsec: uint32(st.Ctim.Nsec), + Sec: st.Ctim.Sec, + }, + // no Atime + }, nil +} diff --git a/auditbeat/helper/hasher/cached_hasher_test.go b/auditbeat/helper/hasher/cached_hasher_test.go new file mode 100644 index 000000000000..7b3374c865a6 --- /dev/null +++ b/auditbeat/helper/hasher/cached_hasher_test.go @@ -0,0 +1,151 @@ +// Licensed to Elasticsearch B.V. under one or more contributor +// license agreements. See the NOTICE file distributed with +// this work for additional information regarding copyright +// ownership. Elasticsearch B.V. licenses this file to you under +// the Apache License, Version 2.0 (the "License"); you may +// not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, +// software distributed under the License is distributed on an +// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +// KIND, either express or implied. See the License for the +// specific language governing permissions and limitations +// under the License. + +//go:build linux + +package hasher + +import ( + "io" + "os" + "testing" + "time" + + "github.com/stretchr/testify/require" +) + +type pattern struct { + text []byte + md5 string + sha1 string + sha256 string + sha512 string + sha3_384 string +} + +var patternA = pattern{ + text: []byte("Rather than love, than money, than fame, give me truth.\n"), + md5: "572698a28f439d3c2647c67df75ed22f", + sha1: "511c4040962d493ba9cb2c0748137c11e42eb46b", + sha256: "19c76b22dd0bf97b0bf064e6587961938ba9f4ab73d034b0edac6c2c2829c0cd", + sha512: "e339322ed81208f930047e8b94db504f40a3e8bb2af75511925e3469488104edcd8eb8c613ea7fd0b08199a4d7061690512a05f66b50b4427470d6c8cf2d74a3", + sha3_384: "9961640983a079920f74f2503feb5ce63325d6a6cd0138905e9419c4307043fa324217587062ac8648cbf43138a33034", +} + +var patternB = pattern{ + text: []byte("From womb to tomb, in kindness and crime.\n"), + md5: "e3d72a80f13b9c1e4b07a7182b934502", + sha1: "90da69d7b93ef792e8e4506543506975018df980", + sha256: "67606f88f25357b2b101e94bd02fc5da8dd2993391b88596c15bea77780a6a77", + sha512: "23c3779d7c6a8d4be2ca7a0bf412a2c99ea2f8a95ac21f56e3b9cb1bd0c0427bf2db91bbb484128f53ef48fbbfc97e525b328e1c4c0f8d24dd8a3f438c449736", + sha3_384: "2034d02ad7b46831b9f2bf09b2eaa77bfcf70ebd136f29b95e6723cc6bf94d0fb7aae972dd2297b5507bb568cb65563b", +} + +var config = Config{ + HashTypes: []HashType{MD5, SHA1, SHA256, SHA512, SHA3_384}, + MaxFileSize: "1 KiB", + MaxFileSizeBytes: 1024, +} + +func TestCachedHasher(t *testing.T) { + ch, err := NewFileHasherWithCache(config, 1) + require.NoError(t, err) + doTestCachedHasher(t, ch) +} + +func TestCachedHasherWithStat(t *testing.T) { + ch, err := NewFileHasherWithCache(config, 1) + require.NoError(t, err) + ch.hasStatx = false + doTestCachedHasher(t, ch) +} + +func doTestCachedHasher(t *testing.T, ch *CachedHasher) { + // Create a file + file := mkTemp(t) + defer file.Close() + + // Write patternA and confirm first hash is a miss + writePattern(t, file, patternA) + ch.checkState(t, file.Name(), patternA, CachedHasherStats{Misses: 1}) + + // Prove a subsequent hash hits the cache + ch.checkState(t, file.Name(), patternA, CachedHasherStats{Misses: 1, Hits: 1}) + + // Prove changing access time still causes a hit. + // Note: we can't use os.Chtimes() to change _only_ atime, it + // might end up modifying mtime since it can round/truncate + // value we would get from file.Stat().ModTime() + time.Sleep(time.Millisecond * 2) + _, err := os.ReadFile(file.Name()) + require.NoError(t, err) + ch.checkState(t, file.Name(), patternA, CachedHasherStats{Misses: 1, Hits: 2}) + + // Prove changing mtime invalides the entry, and causes a miss + ostat, err := file.Stat() + require.NoError(t, err) + mtime := ostat.ModTime().Add(time.Hour) + require.NoError(t, os.Chtimes(file.Name(), mtime, mtime)) + ch.checkState(t, file.Name(), patternA, CachedHasherStats{Misses: 2, Hits: 2, Invalidations: 1}) + + // Write the second pattern, prove it's a miss + writePattern(t, file, patternB) + ch.checkState(t, file.Name(), patternB, CachedHasherStats{Misses: 3, Hits: 2, Invalidations: 2}) + + // Hash something else, prove first one is evicted + file2 := mkTemp(t) + defer file2.Close() + writePattern(t, file2, patternA) + ch.checkState(t, file2.Name(), patternA, CachedHasherStats{Misses: 4, Hits: 2, Invalidations: 2, Evictions: 1}) + + // If we go back and lookup the original path, prove we should evict again and it's a miss + ch.checkState(t, file.Name(), patternB, CachedHasherStats{Misses: 5, Hits: 2, Invalidations: 2, Evictions: 2}) + + // If we close, prove we purge + require.Equal(t, ch.hashLRU.Len(), 1) + ch.Close() + require.Equal(t, ch.hashLRU.Len(), 0) +} + +func mkTemp(t *testing.T) *os.File { + file, err := os.CreateTemp(t.TempDir(), "cached_hasher_test_*") + require.NoError(t, err) + + return file +} + +func writePattern(t *testing.T, file *os.File, p pattern) { + err := file.Truncate(0) + require.NoError(t, err) + _, err = file.Seek(0, io.SeekStart) + require.NoError(t, err) + n, err := file.Write(p.text) + require.NoError(t, err) + require.Equal(t, n, len(p.text)) +} + +func (ch *CachedHasher) checkState(t *testing.T, path string, p pattern, stats CachedHasherStats) { + hashes, err := ch.HashFile(path) + require.NoError(t, err) + require.Len(t, hashes, 5) + require.Equal(t, p.md5, hashes["md5"].String()) + require.Equal(t, p.sha1, hashes["sha1"].String()) + require.Equal(t, p.sha256, hashes["sha256"].String()) + require.Equal(t, p.sha512, hashes["sha512"].String()) + require.Equal(t, p.sha3_384, hashes["sha3_384"].String()) + require.Equal(t, stats, ch.Stats()) +} From f5e21bb507cee2ecf1f4859d4c61d3964a856562 Mon Sep 17 00:00:00 2001 From: Geoff Rowland <70981735+rowlandgeoff@users.noreply.github.com> Date: Wed, 11 Dec 2024 16:43:18 -0500 Subject: [PATCH 39/48] Remove Eng Prod metricbeats tests ownership (#41597) --- .github/CODEOWNERS | 1 - 1 file changed, 1 deletion(-) diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS index 4b179b381449..a06730335729 100644 --- a/.github/CODEOWNERS +++ b/.github/CODEOWNERS @@ -105,7 +105,6 @@ CHANGELOG* /metricbeat/module/system/ @elastic/elastic-agent-data-plane /metricbeat/module/vsphere @elastic/obs-infraobs-integrations /metricbeat/module/zookeeper @elastic/obs-infraobs-integrations -/metricbeat/tests @elastic/ingest-eng-prod /packetbeat/ @elastic/sec-linux-platform /script/ @elastic/elastic-agent-data-plane /testing/ @elastic/elastic-agent-data-plane From f9a9b32e1ae230abe2b0f827850861ead392f1ac Mon Sep 17 00:00:00 2001 From: Marc Guasch Date: Thu, 12 Dec 2024 08:27:47 +0100 Subject: [PATCH 40/48] [filebeat] First unifiedlogs implementation (#41791) * First unifiedlogs implementation * Fix date check and accept multiple predicates * Fix cursor and date walking * Log stderr on error * Add 1s tick * Refactor to do automatic backfill * Add docs and fix resuming from interrupted backfilling * Fix doc config example * Add first unit tests * wip tests * Add stream test * Extract test and make input stable * Improve docs --------- Co-authored-by: r-ung --- CHANGELOG.next.asciidoc | 1 + filebeat/docs/filebeat-options.asciidoc | 3 + .../docs/inputs/input-unifiedlogs.asciidoc | 180 ++++++++ .../input/default-inputs/inputs_darwin.go | 54 +++ .../input/default-inputs/inputs_other.go | 2 +- x-pack/filebeat/input/unifiedlogs/config.go | 75 ++++ x-pack/filebeat/input/unifiedlogs/input.go | 385 +++++++++++++++++ .../filebeat/input/unifiedlogs/input_test.go | 391 ++++++++++++++++++ x-pack/filebeat/input/unifiedlogs/metrics.go | 27 ++ .../testdata/test.logarchive.tar.gz | Bin 0 -> 349382 bytes 10 files changed, 1117 insertions(+), 1 deletion(-) create mode 100644 x-pack/filebeat/docs/inputs/input-unifiedlogs.asciidoc create mode 100644 x-pack/filebeat/input/default-inputs/inputs_darwin.go create mode 100644 x-pack/filebeat/input/unifiedlogs/config.go create mode 100644 x-pack/filebeat/input/unifiedlogs/input.go create mode 100644 x-pack/filebeat/input/unifiedlogs/input_test.go create mode 100644 x-pack/filebeat/input/unifiedlogs/metrics.go create mode 100644 x-pack/filebeat/input/unifiedlogs/testdata/test.logarchive.tar.gz diff --git a/CHANGELOG.next.asciidoc b/CHANGELOG.next.asciidoc index ae41114ae53b..20a6d840a7fb 100644 --- a/CHANGELOG.next.asciidoc +++ b/CHANGELOG.next.asciidoc @@ -358,6 +358,7 @@ https://github.com/elastic/beats/compare/v8.8.1\...main[Check the HEAD diff] - Add ability to remove request trace logs from entityanalytics input. {pull}40004[40004] - Refactor & cleanup with updates to default values and documentation. {pull}41834[41834] - Update CEL mito extensions to v1.16.0. {pull}41727[41727] +- Add `unifiedlogs` input for MacOS. {pull}41791[41791] - Add evaluation state dump debugging option to CEL input. {pull}41335[41335] - Added support for retry configuration in GCS input. {issue}11580[11580] {pull}41862[41862] - Improve S3 polling mode states registry when using list prefix option. {pull}41869[41869] diff --git a/filebeat/docs/filebeat-options.asciidoc b/filebeat/docs/filebeat-options.asciidoc index 3b1d274d59bd..5e77999a00b3 100644 --- a/filebeat/docs/filebeat-options.asciidoc +++ b/filebeat/docs/filebeat-options.asciidoc @@ -95,6 +95,7 @@ You can configure {beatname_uc} to use the following inputs: * <<{beatname_lc}-input-syslog>> * <<{beatname_lc}-input-tcp>> * <<{beatname_lc}-input-udp>> +* <<{beatname_lc}-input-unifiedlogs>> * <<{beatname_lc}-input-unix>> * <<{beatname_lc}-input-winlog>> @@ -158,6 +159,8 @@ include::inputs/input-tcp.asciidoc[] include::inputs/input-udp.asciidoc[] +include::../../x-pack/filebeat/docs/inputs/input-unifiedlogs.asciidoc[] + include::inputs/input-unix.asciidoc[] include::inputs/input-winlog.asciidoc[] diff --git a/x-pack/filebeat/docs/inputs/input-unifiedlogs.asciidoc b/x-pack/filebeat/docs/inputs/input-unifiedlogs.asciidoc new file mode 100644 index 000000000000..37589f307fb3 --- /dev/null +++ b/x-pack/filebeat/docs/inputs/input-unifiedlogs.asciidoc @@ -0,0 +1,180 @@ +[role="xpack"] + +:type: unifiedlogs + +[id="{beatname_lc}-input-{type}"] +=== Unified Logs input + +++++ +Unified Logs +++++ + +NOTE: Only available for MacOS. + +The unified logging system provides a comprehensive and performant API to capture +telemetry across all levels of the system. This system centralizes the storage of +log data in memory and on disk, rather than writing that data to a text-based log file. + +The input interacts with the `log` command-line tool to provide access to the events. + +The input starts streaming events from the current point in time unless a start date or +the `backfill` options are set. When restarted it will continue where it left off. + +Alternatively, it can also do one off operations, such as: + +- Stream events contained in a `.logarchive` file. +- Stream events contained in a `.tracev3` file. +- Stream events in a specific time span, by providing a specific end date. + +After this one off operations complete, the input will stop. + +Other configuration options can be specified to filter what events to process. + +NOTE: The input can cause some duplicated events when backfilling and/or +restarting. This is caused by how the underlying fetching method works and +should be taken into account when using the input. + +Example configuration: + +Process all old and new logs: + +["source","yaml",subs="attributes"] +---- +{beatname_lc}.inputs: +- type: unifiedlogs + id: unifiedlogs-id + enabled: true + backfill: true +---- + +Process logs with predicate filters: + +["source","yaml",subs="attributes"] +---- +{beatname_lc}.inputs: +- type: unifiedlogs + id: unifiedlogs-id + enabled: true + predicate: + # Captures keychain.db unlock events + - 'process == "loginwindow" && sender == "Security"' + # Captures user login events + - 'process == "logind"' + # Captures command line activity run with elevated privileges + - 'process == "sudo"' +---- + +==== Configuration options + +The `unifiedlogs` input supports the following configuration options plus the +<<{beatname_lc}-input-{type}-common-options>> described later. + +[float] +==== `archive_file` + +Display events stored in the given archive. +The archive must be a valid log archive bundle with the suffix `.logarchive`. + +[float] +==== `trace_file` + +Display events stored in the given `.tracev3` file. +In order to be decoded, the file must be contained within a valid `.logarchive` + +[float] +==== `start` + +Shows content starting from the provided date. +The following date/time formats are accepted: +`YYYY-MM-DD`, `YYYY-MM-DD HH:MM:SS`, `YYYY-MM-DD HH:MM:SSZZZZZ`. + +[float] +==== `end` + +Shows content up to the provided date. +The following date/time formats are accepted: +`YYYY-MM-DD`, `YYYY-MM-DD HH:MM:SS`, `YYYY-MM-DD HH:MM:SSZZZZZ`. + +[float] +==== `predicate` + +Filters messages using the provided predicate based on NSPredicate. +A compound predicate or multiple predicates can be provided as a list. + +For detailed information on the use of predicate based filtering, +please refer to the https://developer.apple.com/library/mac/documentation/Cocoa/Conceptual/Predicates/Articles/pSyntax.html[Predicate Programming Guide]. + +[float] +==== `process` + +A list of the processes on which to operate. It accepts a PID or process name. + +[float] +==== `source` + +Include symbol names and source line numbers for messages, if available. +Default: `false`. + +[float] +==== `info` + +Disable or enable info level messages. +Default: `false`. + +[float] +==== `debug` + +Disable or enable debug level messages. +Default: `false`. + +[float] +==== `backtrace` + +Disable or enable display of backtraces. +Default: `false`. + +[float] +==== `signpost` + +Disable or enable display of signposts. +Default: `false`. + +[float] +==== `unreliable` + +Annotate events with whether the log was emitted unreliably. +Default: `false`. + +[float] +==== `mach_continuous_time` + +Use mach continuous time timestamps rather than walltime. +Default: `false`. + +[float] +==== `backfill` + +If set to true the input will process all available logs since the beginning +of time the first time it starts. +Default: `false`. + + +[id="{beatname_lc}-input-{type}-common-options"] +include::../../../../filebeat/docs/inputs/input-common-options.asciidoc[] + +[float] +=== Metrics + +This input exposes metrics under the <>. +These metrics are exposed under the `/inputs/` path. They can be used to +observe the activity of the input. + +You must assign a unique `id` to the input to expose metrics. + +[options="header"] +|======= +| Metric | Description +| `errors_total` | Total number of errors. +|======= + +:type!: diff --git a/x-pack/filebeat/input/default-inputs/inputs_darwin.go b/x-pack/filebeat/input/default-inputs/inputs_darwin.go new file mode 100644 index 000000000000..b43d75258b35 --- /dev/null +++ b/x-pack/filebeat/input/default-inputs/inputs_darwin.go @@ -0,0 +1,54 @@ +// Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one +// or more contributor license agreements. Licensed under the Elastic License; +// you may not use this file except in compliance with the Elastic License. + +//go:build darwin + +package inputs + +import ( + "github.com/elastic/beats/v7/filebeat/beater" + v2 "github.com/elastic/beats/v7/filebeat/input/v2" + "github.com/elastic/beats/v7/libbeat/beat" + "github.com/elastic/beats/v7/x-pack/filebeat/input/awscloudwatch" + "github.com/elastic/beats/v7/x-pack/filebeat/input/awss3" + "github.com/elastic/beats/v7/x-pack/filebeat/input/azureblobstorage" + "github.com/elastic/beats/v7/x-pack/filebeat/input/azureeventhub" + "github.com/elastic/beats/v7/x-pack/filebeat/input/benchmark" + "github.com/elastic/beats/v7/x-pack/filebeat/input/cel" + "github.com/elastic/beats/v7/x-pack/filebeat/input/cloudfoundry" + "github.com/elastic/beats/v7/x-pack/filebeat/input/entityanalytics" + "github.com/elastic/beats/v7/x-pack/filebeat/input/gcs" + "github.com/elastic/beats/v7/x-pack/filebeat/input/http_endpoint" + "github.com/elastic/beats/v7/x-pack/filebeat/input/httpjson" + "github.com/elastic/beats/v7/x-pack/filebeat/input/lumberjack" + "github.com/elastic/beats/v7/x-pack/filebeat/input/netflow" + "github.com/elastic/beats/v7/x-pack/filebeat/input/o365audit" + "github.com/elastic/beats/v7/x-pack/filebeat/input/salesforce" + "github.com/elastic/beats/v7/x-pack/filebeat/input/streaming" + "github.com/elastic/beats/v7/x-pack/filebeat/input/unifiedlogs" + "github.com/elastic/elastic-agent-libs/logp" +) + +func xpackInputs(info beat.Info, log *logp.Logger, store beater.StateStore) []v2.Plugin { + return []v2.Plugin{ + azureblobstorage.Plugin(log, store), + azureeventhub.Plugin(log), + cel.Plugin(log, store), + cloudfoundry.Plugin(), + entityanalytics.Plugin(log), + gcs.Plugin(log, store), + http_endpoint.Plugin(), + httpjson.Plugin(log, store), + o365audit.Plugin(log, store), + awss3.Plugin(store), + awscloudwatch.Plugin(), + lumberjack.Plugin(), + salesforce.Plugin(log, store), + streaming.Plugin(log, store), + streaming.PluginWebsocketAlias(log, store), + netflow.Plugin(log), + benchmark.Plugin(), + unifiedlogs.Plugin(log, store), + } +} diff --git a/x-pack/filebeat/input/default-inputs/inputs_other.go b/x-pack/filebeat/input/default-inputs/inputs_other.go index 731f8979766e..a14145a5265f 100644 --- a/x-pack/filebeat/input/default-inputs/inputs_other.go +++ b/x-pack/filebeat/input/default-inputs/inputs_other.go @@ -2,7 +2,7 @@ // or more contributor license agreements. Licensed under the Elastic License; // you may not use this file except in compliance with the Elastic License. -//go:build !aix && !windows +//go:build !aix && !darwin && !windows package inputs diff --git a/x-pack/filebeat/input/unifiedlogs/config.go b/x-pack/filebeat/input/unifiedlogs/config.go new file mode 100644 index 000000000000..0999e7d768b8 --- /dev/null +++ b/x-pack/filebeat/input/unifiedlogs/config.go @@ -0,0 +1,75 @@ +// Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one +// or more contributor license agreements. Licensed under the Elastic License; +// you may not use this file except in compliance with the Elastic License. + +//go:build darwin + +package unifiedlogs + +import ( + "fmt" + "strings" + "time" +) + +type config struct { + showConfig + commonConfig + Backfill bool `config:"backfill"` +} + +type showConfig struct { + ArchiveFile string `config:"archive_file"` + TraceFile string `config:"trace_file"` + Start string `config:"start"` + End string `config:"end"` +} + +type commonConfig struct { + Predicate []string `config:"predicate"` + Process []string `config:"process"` + Source bool `config:"source"` + Info bool `config:"info"` + Debug bool `config:"debug"` + Backtrace bool `config:"backtrace"` + Signpost bool `config:"signpost"` + Unreliable bool `config:"unreliable"` + MachContinuousTime bool `config:"mach_continuous_time"` +} + +func (c config) Validate() error { + if err := checkDateFormat(c.Start); err != nil { + return fmt.Errorf("start date is not valid: %w", err) + } + if err := checkDateFormat(c.End); err != nil { + return fmt.Errorf("end date is not valid: %w", err) + } + if c.ArchiveFile != "" && !strings.HasSuffix(c.ArchiveFile, ".logarchive") { + return fmt.Errorf("archive_file %v has the wrong extension", c.ArchiveFile) + } + if c.TraceFile != "" && !strings.HasSuffix(c.TraceFile, ".tracev3") { + return fmt.Errorf("trace_file %v has the wrong extension", c.TraceFile) + } + return nil +} + +func defaultConfig() config { + return config{} +} + +func checkDateFormat(date string) error { + if date == "" { + return nil + } + acceptedLayouts := []string{ + "2006-01-02", + "2006-01-02 15:04:05", + "2006-01-02 15:04:05-0700", + } + for _, layout := range acceptedLayouts { + if _, err := time.Parse(layout, date); err == nil { + return nil + } + } + return fmt.Errorf("not a valid date, accepted layouts are: %v", acceptedLayouts) +} diff --git a/x-pack/filebeat/input/unifiedlogs/input.go b/x-pack/filebeat/input/unifiedlogs/input.go new file mode 100644 index 000000000000..ca33c03c3bb6 --- /dev/null +++ b/x-pack/filebeat/input/unifiedlogs/input.go @@ -0,0 +1,385 @@ +// Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one +// or more contributor license agreements. Licensed under the Elastic License; +// you may not use this file except in compliance with the Elastic License. + +//go:build darwin + +package unifiedlogs + +import ( + "bufio" + "context" + "encoding/json" + "fmt" + "io" + "os/exec" + "sync" + "sync/atomic" + "time" + + "golang.org/x/sync/errgroup" + + v2 "github.com/elastic/beats/v7/filebeat/input/v2" + inputcursor "github.com/elastic/beats/v7/filebeat/input/v2/input-cursor" + "github.com/elastic/beats/v7/libbeat/beat" + "github.com/elastic/beats/v7/libbeat/feature" + "github.com/elastic/beats/v7/libbeat/monitoring/inputmon" + conf "github.com/elastic/elastic-agent-libs/config" + "github.com/elastic/elastic-agent-libs/logp" + "github.com/elastic/elastic-agent-libs/mapstr" + "github.com/elastic/go-concert/ctxtool" +) + +const ( + inputName = "unifiedlogs" + srcArchiveName = "log-cmd-archive" + srcPollName = "log-cmd-poll" + logDateLayout = "2006-01-02 15:04:05.999999-0700" + cursorDateLayout = "2006-01-02 15:04:05-0700" +) + +var ( + // override for testing + timeNow = time.Now +) + +func Plugin(log *logp.Logger, store inputcursor.StateStore) v2.Plugin { + return v2.Plugin{ + Name: inputName, + Stability: feature.Stable, + Deprecated: false, + Manager: &inputcursor.InputManager{ + Logger: log, + StateStore: store, + Type: inputName, + Configure: cursorConfigure, + }, + } +} + +type logRecord struct { + Timestamp string `json:"timestamp"` +} + +type source struct { + name string +} + +func newSource(config config) source { + if config.ArchiveFile != "" || config.TraceFile != "" { + return source{name: srcArchiveName} + } + return source{name: srcPollName} +} + +func (src source) Name() string { return src.name } + +type input struct { + config + metrics *inputMetrics +} + +func cursorConfigure(cfg *conf.C) ([]inputcursor.Source, inputcursor.Input, error) { + conf := defaultConfig() + if err := cfg.Unpack(&conf); err != nil { + return nil, nil, err + } + sources, inp := newCursorInput(conf) + return sources, inp, nil +} + +func newCursorInput(config config) ([]inputcursor.Source, inputcursor.Input) { + input := &input{config: config} + return []inputcursor.Source{newSource(config)}, input +} + +func (input) Name() string { return inputName } + +func (input input) Test(src inputcursor.Source, _ v2.TestContext) error { + if _, err := exec.LookPath("log"); err != nil { + return err + } + return nil +} + +// Run starts the input and blocks until it ends the execution. +func (input *input) Run(ctxt v2.Context, src inputcursor.Source, resumeCursor inputcursor.Cursor, pub inputcursor.Publisher) error { + reg, unreg := inputmon.NewInputRegistry(input.Name(), ctxt.ID, nil) + defer unreg() + input.metrics = newInputMetrics(reg) + + stdCtx := ctxtool.FromCanceller(ctxt.Cancelation) + log := ctxt.Logger.With("source", src.Name()) + + startFrom, err := loadCursor(resumeCursor, log) + if err != nil { + return err + } + if startFrom != "" { + input.Start = startFrom + } + + return input.runWithMetrics(stdCtx, pub, log) +} + +func (input *input) runWithMetrics(ctx context.Context, pub inputcursor.Publisher, log *logp.Logger) error { + // we create a wrapped publisher for the streaming go routine. + // It will notify the backfilling goroutine with the end date of the + // backfilling period and avoid updating the stored date to resume + // until backfilling is done. + wrappedPub := newWrappedPublisher(!input.mustBackfill(), pub) + + var g errgroup.Group + // we start the streaming command in the background + // it will use the wrapped publisher to set the end date for the + // backfilling process. + if input.mustStream() { + g.Go(func() error { + logCmd := newLogStreamCmd(ctx, input.commonConfig) + return input.runLogCmd(ctx, logCmd, wrappedPub, log) + }) + } + + if input.mustBackfill() { + g.Go(func() error { + if input.mustStream() { + t := wrappedPub.getFirstProcessedTime() + // The time resolution of the log tool is microsecond, while it only + // accepts second resolution as an end parameter. + // To avoid potentially losing data we move the end forward one second, + // since it is preferable to have some duplicated events. + t = t.Add(time.Second) + input.End = t.Format(cursorDateLayout) + + // to avoid race conditions updating the cursor, and to be able to + // resume from the oldest point in time, we only update cursor + // from the streaming goroutine once backfilling is done. + defer wrappedPub.startUpdatingCursor() + } + logCmd := newLogShowCmd(ctx, input.config) + err := input.runLogCmd(ctx, logCmd, pub, log) + if !input.mustStream() { + log.Debugf("finished processing events, stopping") + } + return err + }) + } + + return g.Wait() +} + +// mustStream returns true in case a stream command is needed. +// This is the default case and the only exceptions are when an archive file or an end date are set. +func (input *input) mustStream() bool { + return !(input.ArchiveFile != "" || input.TraceFile != "" || input.End != "") +} + +// mustBackfill returns true in case a show command is needed. +// This happens when start or end dates are set (for example when resuming filebeat), when an archive file is used, +// or when user forces it via the backfill config. +func (input *input) mustBackfill() bool { + return input.Backfill || input.ArchiveFile != "" || input.TraceFile != "" || input.Start != "" || input.End != "" +} + +func (input *input) runLogCmd(ctx context.Context, logCmd *exec.Cmd, pub inputcursor.Publisher, log *logp.Logger) error { + outpipe, err := logCmd.StdoutPipe() + if err != nil { + return fmt.Errorf("get stdout pipe: %w", err) + } + errpipe, err := logCmd.StderrPipe() + if err != nil { + return fmt.Errorf("get stderr pipe: %w", err) + } + + log.Debugf("exec command start: %v", logCmd) + defer log.Debugf("exec command end: %v", logCmd) + + if err := logCmd.Start(); err != nil { + return fmt.Errorf("start log command: %w", err) + } + + if err := input.processLogs(outpipe, pub, log); err != nil { + log.Errorf("process logs: %v", err) + } + + stderrBytes, _ := io.ReadAll(errpipe) + if err := logCmd.Wait(); err != nil && ctx.Err() == nil { + return fmt.Errorf("%q exited with an error: %w, %q", logCmd, err, string(stderrBytes)) + } + + return nil +} + +func (input *input) processLogs(stdout io.Reader, pub inputcursor.Publisher, log *logp.Logger) error { + scanner := bufio.NewScanner(stdout) + + var ( + event beat.Event + line string + logRecordLine logRecord + timestamp time.Time + err error + ) + + for scanner.Scan() { + line = scanner.Text() + if err = json.Unmarshal([]byte(line), &logRecordLine); err != nil { + log.Errorf("invalid json log: %v", err) + input.metrics.errs.Add(1) + continue + } + + if logRecordLine == (logRecord{}) { + continue + } + + timestamp, err = time.Parse(logDateLayout, logRecordLine.Timestamp) + if err != nil { + input.metrics.errs.Add(1) + log.Errorf("invalid timestamp: %v", err) + continue + } + + event = makeEvent(timestamp, line) + if err = pub.Publish(event, timestamp); err != nil { + log.Errorf("publish event: %v", err) + input.metrics.errs.Add(1) + continue + } + } + if err = scanner.Err(); err != nil { + input.metrics.errs.Add(1) + return fmt.Errorf("scanning stdout: %w", err) + } + + return nil +} + +// wrappedPublisher wraps a publisher and stores the first published event date. +// this is required in order to backfill the events when we start a streaming command. +type wrappedPublisher struct { + firstTimeOnce sync.Once + firstTimeC chan struct{} + firstProcessedTime time.Time + + updateCursor *atomic.Bool + + inner inputcursor.Publisher +} + +func newWrappedPublisher(updateCursor bool, inner inputcursor.Publisher) *wrappedPublisher { + var atomicUC atomic.Bool + atomicUC.Store(updateCursor) + return &wrappedPublisher{ + firstTimeC: make(chan struct{}), + updateCursor: &atomicUC, + inner: inner, + } +} + +func (pub *wrappedPublisher) Publish(event beat.Event, cursor interface{}) error { + pub.firstTimeOnce.Do(func() { + pub.firstProcessedTime = cursor.(time.Time) + close(pub.firstTimeC) + }) + if !pub.updateCursor.Load() { + cursor = nil + } + return pub.inner.Publish(event, cursor) +} + +// getFirstProcessedTime will block until there is a value set for firstProcessedTime. +func (pub *wrappedPublisher) getFirstProcessedTime() time.Time { + <-pub.firstTimeC + return pub.firstProcessedTime +} + +func (pub *wrappedPublisher) startUpdatingCursor() { + pub.updateCursor.Store(true) +} + +func loadCursor(c inputcursor.Cursor, log *logp.Logger) (string, error) { + if c.IsNew() { + return "", nil + } + var ( + startFrom string + cursor time.Time + ) + if err := c.Unpack(&cursor); err != nil { + return "", fmt.Errorf("unpack cursor: %w", err) + } + log.Infof("cursor loaded, resuming from: %v", startFrom) + return cursor.Format(cursorDateLayout), nil +} + +func newLogShowCmd(ctx context.Context, cfg config) *exec.Cmd { + return exec.CommandContext(ctx, "log", newLogCmdArgs("show", cfg)...) // #nosec G204 +} + +func newLogStreamCmd(ctx context.Context, cfg commonConfig) *exec.Cmd { + return exec.CommandContext(ctx, "log", newLogCmdArgs("stream", config{commonConfig: cfg})...) // #nosec G204 +} + +func newLogCmdArgs(subcmd string, config config) []string { + args := []string{subcmd, "--style", "ndjson"} + if config.ArchiveFile != "" { + args = append(args, "--archive", config.ArchiveFile) + } + if config.TraceFile != "" { + args = append(args, "--file", config.TraceFile) + } + if len(config.Predicate) > 0 { + for _, p := range config.Predicate { + args = append(args, "--predicate", p) + } + } + if len(config.Process) > 0 { + for _, p := range config.Process { + args = append(args, "--process", p) + } + } + if config.Source { + args = append(args, "--source") + } + if config.Info { + args = append(args, "--info") + } + if config.Debug { + args = append(args, "--debug") + } + if config.Backtrace { + args = append(args, "--backtrace") + } + if config.Signpost { + args = append(args, "--signpost") + } + if config.Unreliable { + args = append(args, "--unreliable") + } + if config.MachContinuousTime { + args = append(args, "--mach-continuous-time") + } + if config.Start != "" { + args = append(args, "--start", config.Start) + } + if config.End != "" { + args = append(args, "--end", config.End) + } + return args +} + +func makeEvent(timestamp time.Time, message string) beat.Event { + now := timeNow() + fields := mapstr.M{ + "event": mapstr.M{ + "created": now, + }, + "message": message, + } + + return beat.Event{ + Timestamp: timestamp, + Fields: fields, + } +} diff --git a/x-pack/filebeat/input/unifiedlogs/input_test.go b/x-pack/filebeat/input/unifiedlogs/input_test.go new file mode 100644 index 000000000000..907c927254d3 --- /dev/null +++ b/x-pack/filebeat/input/unifiedlogs/input_test.go @@ -0,0 +1,391 @@ +// Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one +// or more contributor license agreements. Licensed under the Elastic License; +// you may not use this file except in compliance with the Elastic License. + +//go:build darwin + +package unifiedlogs + +import ( + "bufio" + "bytes" + "context" + "fmt" + "os" + "os/exec" + "path" + "regexp" + "strings" + "sync" + "testing" + "time" + + "github.com/stretchr/testify/assert" + "github.com/stretchr/testify/require" + + inputcursor "github.com/elastic/beats/v7/filebeat/input/v2/input-cursor" + "github.com/elastic/beats/v7/libbeat/beat" + "github.com/elastic/elastic-agent-libs/logp" +) + +var _ inputcursor.Publisher = (*publisher)(nil) + +type publisher struct { + m sync.Mutex + + events []beat.Event + cursors []*time.Time +} + +func (p *publisher) Publish(e beat.Event, cursor interface{}) error { + p.m.Lock() + defer p.m.Unlock() + + p.events = append(p.events, e) + var c *time.Time + if cursor != nil { + cv := cursor.(time.Time) + c = &cv + } + p.cursors = append(p.cursors, c) + return nil +} + +func TestInput(t *testing.T) { + archivePath, err := openArchive() + require.NoError(t, err) + t.Cleanup(func() { os.RemoveAll(archivePath) }) + + testCases := []struct { + name string + cfg config + timeUntilClose time.Duration + assertFunc func(collect *assert.CollectT, events []beat.Event, cursors []*time.Time) + expectedLogStreamCmd string + expectedLogShowCmd string + expectedRunErrorMsg string + }{ + { + name: "Default stream", + cfg: config{}, + timeUntilClose: time.Second, + expectedLogStreamCmd: "/usr/bin/log stream --style ndjson", + assertFunc: func(collect *assert.CollectT, events []beat.Event, cursors []*time.Time) { + assert.NotEmpty(collect, events) + assert.NotEmpty(collect, cursors) + assert.Equal(collect, len(events), len(cursors)) + lastEvent := events[len(events)-1] + lastCursor := cursors[len(cursors)-1] + assert.EqualValues(collect, &lastEvent.Timestamp, lastCursor) + }, + }, + { + name: "Archive not found", + cfg: config{ + showConfig: showConfig{ + ArchiveFile: "notfound.logarchive", + }, + }, + timeUntilClose: time.Second, + expectedLogShowCmd: "/usr/bin/log show --style ndjson --archive notfound.logarchive", + expectedRunErrorMsg: "\"/usr/bin/log show --style ndjson --archive notfound.logarchive\" exited with an error: exit status 64", + }, + { + name: "Archived file", + cfg: config{ + showConfig: showConfig{ + ArchiveFile: archivePath, + }, + }, + timeUntilClose: time.Second, + expectedLogShowCmd: fmt.Sprintf("/usr/bin/log show --style ndjson --archive %s", archivePath), + assertFunc: eventsAndCursorAssertN(462), + }, + { + name: "Trace file", + cfg: config{ + showConfig: showConfig{ + TraceFile: path.Join(archivePath, "logdata.LiveData.tracev3"), + }, + }, + timeUntilClose: time.Second, + expectedLogShowCmd: fmt.Sprintf("/usr/bin/log show --style ndjson --file %s", path.Join(archivePath, "logdata.LiveData.tracev3")), + assertFunc: eventsAndCursorAssertN(7), + }, + { + name: "With start date", + cfg: config{ + showConfig: showConfig{ + ArchiveFile: archivePath, + Start: "2024-12-04 13:46:00+0200", + }, + }, + timeUntilClose: time.Second, + expectedLogShowCmd: fmt.Sprintf("/usr/bin/log show --style ndjson --archive %s --start 2024-12-04 13:46:00+0200", archivePath), + assertFunc: eventsAndCursorAssertN(314), + }, + { + name: "With start and end dates", + cfg: config{ + showConfig: showConfig{ + ArchiveFile: archivePath, + Start: "2024-12-04 13:45:00+0200", + End: "2024-12-04 13:46:00+0200", + }, + }, + timeUntilClose: time.Second, + expectedLogShowCmd: fmt.Sprintf("/usr/bin/log show --style ndjson --archive %s --start 2024-12-04 13:45:00+0200 --end 2024-12-04 13:46:00+0200", archivePath), + assertFunc: eventsAndCursorAssertN(149), + }, + { + name: "With end date", + cfg: config{ + showConfig: showConfig{ + ArchiveFile: archivePath, + End: "2024-12-04 13:46:00+0200", + }, + }, + timeUntilClose: time.Second, + expectedLogShowCmd: fmt.Sprintf("/usr/bin/log show --style ndjson --archive %s --end 2024-12-04 13:46:00+0200", archivePath), + assertFunc: eventsAndCursorAssertN(462), + }, + { + name: "With predicate", + cfg: config{ + showConfig: showConfig{ + ArchiveFile: archivePath, + }, + commonConfig: commonConfig{ + Predicate: []string{ + `processImagePath == "/kernel"`, + }, + }, + }, + timeUntilClose: time.Second, + expectedLogShowCmd: fmt.Sprintf("/usr/bin/log show --style ndjson --archive %s --predicate processImagePath == \"/kernel\"", archivePath), + assertFunc: eventsAndCursorAssertN(460), + }, + { + name: "With process", + cfg: config{ + showConfig: showConfig{ + ArchiveFile: archivePath, + }, + commonConfig: commonConfig{ + Process: []string{ + "0", + }, + }, + }, + timeUntilClose: time.Second, + expectedLogShowCmd: fmt.Sprintf("/usr/bin/log show --style ndjson --archive %s --process 0", archivePath), + assertFunc: eventsAndCursorAssertN(462), + }, + { + name: "With optional flags", + cfg: config{ + showConfig: showConfig{ + ArchiveFile: archivePath, + }, + commonConfig: commonConfig{ + Info: true, + Debug: true, + Backtrace: true, + Signpost: true, + MachContinuousTime: true, + }, + }, + timeUntilClose: time.Second, + expectedLogShowCmd: fmt.Sprintf("/usr/bin/log show --style ndjson --archive %s --info --debug --backtrace --signpost --mach-continuous-time", archivePath), + assertFunc: eventsAndCursorAssertN(462), + }, + } + + for _, tc := range testCases { + tc := tc + t.Run(tc.name, func(t *testing.T) { + _, cursorInput := newCursorInput(tc.cfg) + input := cursorInput.(*input) + + ctx, cancel := context.WithCancel(context.Background()) + + pub := &publisher{} + log, buf := logp.NewInMemory("unifiedlogs_test", logp.JSONEncoderConfig()) + + var wg sync.WaitGroup + wg.Add(1) + go func(t *testing.T) { + defer wg.Done() + err := input.runWithMetrics(ctx, pub, log) + if tc.expectedRunErrorMsg == "" { + assert.NoError(t, err) + } else { + assert.ErrorContains(t, err, tc.expectedRunErrorMsg) + } + }(t) + + select { + case <-ctx.Done(): + case <-time.After(tc.timeUntilClose): + } + + cancel() + wg.Wait() + + assert.EventuallyWithT(t, + func(collect *assert.CollectT) { + assert.Equal(collect, tc.expectedLogStreamCmd, filterStartLogStreamLogline(buf.Bytes())) + assert.Equal(collect, tc.expectedLogShowCmd, filterStartLogShowLogline(buf.Bytes())) + if tc.assertFunc != nil { + tc.assertFunc(collect, pub.events, pub.cursors) + } + }, + 30*time.Second, time.Second, + ) + }) + } +} + +func TestBackfillAndStream(t *testing.T) { + archivePath, err := openArchive() + require.NoError(t, err) + t.Cleanup(func() { os.RemoveAll(archivePath) }) + + cfg := config{ + Backfill: true, + showConfig: showConfig{ + Start: time.Now().Add(-5 * time.Second).Format("2006-01-02 15:04:05"), + }, + commonConfig: commonConfig{ + Info: true, + Debug: true, + Backtrace: true, + Signpost: true, + MachContinuousTime: true, + }, + } + + expectedLogShowCmd := fmt.Sprintf("/usr/bin/log show --style ndjson --info --debug --backtrace --signpost --mach-continuous-time --start %v", time.Now().Format("2006-01-02")) + expectedLogStreamCmd := "/usr/bin/log stream --style ndjson --info --debug --backtrace --signpost --mach-continuous-time" + + _, cursorInput := newCursorInput(cfg) + input := cursorInput.(*input) + + ctx, cancel := context.WithCancel(context.Background()) + t.Cleanup(cancel) + + pub := &publisher{} + log, buf := logp.NewInMemory("unifiedlogs_test", logp.JSONEncoderConfig()) + + var wg sync.WaitGroup + wg.Add(1) + go func(t *testing.T) { + defer wg.Done() + err := input.runWithMetrics(ctx, pub, log) + assert.NoError(t, err) + }(t) + + var firstStreamedEventTime *time.Time + assert.EventuallyWithT(t, + func(collect *assert.CollectT) { + showCmdLog := filterStartLogShowLogline(buf.Bytes()) + assert.Equal(collect, expectedLogStreamCmd, filterStartLogStreamLogline(buf.Bytes())) + assert.True(collect, strings.HasPrefix(showCmdLog, expectedLogShowCmd)) + assert.NotEmpty(collect, pub.events) + assert.NotEmpty(collect, pub.cursors) + + var endTime time.Time + regex := regexp.MustCompile(`--end\s+(\d{4}-\d{2}-\d{2}\s\d{2}:\d{2}:\d{2}[+-]\d{4})`) + matches := regex.FindStringSubmatch(showCmdLog) + assert.Equal(collect, 2, len(matches)) + endTime, _ = time.Parse("2006-01-02 15:04:05-0700", matches[1]) + endTime = endTime.Truncate(time.Second) + + if firstStreamedEventTime == nil { + for i := range pub.events { + if pub.cursors[i] == nil { + first := pub.events[i].Timestamp.Add(time.Second).Truncate(time.Second) + firstStreamedEventTime = &first + break + } + } + } + assert.NotNil(collect, firstStreamedEventTime) + assert.EqualValues(collect, endTime, *firstStreamedEventTime) + assert.True(collect, strings.HasPrefix(showCmdLog, filterEndLogShowLogline(buf.Bytes()))) + }, + 30*time.Second, time.Second, + ) + + cancel() + wg.Wait() +} + +const ( + cmdStartPrefix = "exec command start: " + cmdEndPrefix = "exec command end: " +) + +func filterStartLogStreamLogline(buf []byte) string { + const cmd = "/usr/bin/log stream" + return filterLogCmdLine(buf, cmd, cmdStartPrefix) +} + +func filterStartLogShowLogline(buf []byte) string { + const cmd = "/usr/bin/log show" + return filterLogCmdLine(buf, cmd, cmdStartPrefix) +} + +func filterEndLogShowLogline(buf []byte) string { + const cmd = "/usr/bin/log show" + return filterLogCmdLine(buf, cmd, cmdEndPrefix) +} + +func filterLogCmdLine(buf []byte, cmd, cmdPrefix string) string { + scanner := bufio.NewScanner(bytes.NewBuffer(buf)) + for scanner.Scan() { + text := scanner.Text() + parts := strings.Split(text, "\t") + if len(parts) != 4 { + continue + } + + trimmed := strings.TrimPrefix(parts[3], cmdStartPrefix) + if strings.HasPrefix(trimmed, cmd) { + return trimmed + } + } + return "" +} + +func eventsAndCursorAssertN(n int) func(collect *assert.CollectT, events []beat.Event, cursors []*time.Time) { + return func(collect *assert.CollectT, events []beat.Event, cursors []*time.Time) { + assert.Equal(collect, n, len(events)) + assert.Equal(collect, n, len(cursors)) + lastEvent := events[len(events)-1] + lastCursor := cursors[len(cursors)-1] + assert.EqualValues(collect, &lastEvent.Timestamp, lastCursor) + } +} + +func openArchive() (string, error) { + return extractTarGz(path.Join("testdata", "test.logarchive.tar.gz")) +} + +func extractTarGz(tarGzPath string) (string, error) { + // Create a temporary directory + tempDir, err := os.MkdirTemp("", "extracted-*") + if err != nil { + return "", fmt.Errorf("failed to create temporary directory: %v", err) + } + + // Use the 'tar' command to extract the .tar.gz file + cmd := exec.Command("tar", "-xzf", tarGzPath, "-C", tempDir) + + // Run the command + if err := cmd.Run(); err != nil { + return "", fmt.Errorf("failed to extract .tar.gz: %v", err) + } + + return path.Join(tempDir, "test.logarchive"), nil +} diff --git a/x-pack/filebeat/input/unifiedlogs/metrics.go b/x-pack/filebeat/input/unifiedlogs/metrics.go new file mode 100644 index 000000000000..2e24c0b4121f --- /dev/null +++ b/x-pack/filebeat/input/unifiedlogs/metrics.go @@ -0,0 +1,27 @@ +// Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one +// or more contributor license agreements. Licensed under the Elastic License; +// you may not use this file except in compliance with the Elastic License. + +//go:build darwin + +package unifiedlogs + +import ( + "github.com/elastic/elastic-agent-libs/monitoring" +) + +type inputMetrics struct { + errs *monitoring.Uint // total number of errors +} + +func newInputMetrics(reg *monitoring.Registry) *inputMetrics { + if reg == nil { + return nil + } + + out := &inputMetrics{ + errs: monitoring.NewUint(reg, "errors_total"), + } + + return out +} diff --git a/x-pack/filebeat/input/unifiedlogs/testdata/test.logarchive.tar.gz b/x-pack/filebeat/input/unifiedlogs/testdata/test.logarchive.tar.gz new file mode 100644 index 0000000000000000000000000000000000000000..fc507f9b1e9e4365457a6ca42ffcae3df4db9da7 GIT binary patch literal 349382 zcmY&;V{j%+&~0qnwzIKqZIa#Cwr$(CH`qAY*xEQxY}6B0n&;N!R?gCY=x%QbUhaOD>q+!{Iv%k#=AY->yCQQN5M_=9liY5li;ZEfw!d4@g^KaTok z>R>q9hz|4htGNR+aVBiJ-O~F{cOAwU>gg&P;)aB z=sx+r&HWkvauaSN)%9om*vM(BukvpoG6-m1I#!5&*5{xNTBXZl5@^=mWrkJGn=%Es z=MR5WB)pegf{;Kxe`-Vu({p)CgEk!dMGAG6Me>gPxjZQ>b6(W}@4vm>B7V(m1bzzq z_(To3xe*rjdF6*6^zS1aI=FgY!F)+ONQ{8gC zF8#n=8@PEg*5Px;SBG2sdAZw^i9eQqw1tG!ngL6}9uH|L~$DPPfNY7Hx?WbeS%Joqn=}|`osCOgL`^%G%)Bwth=N%OQT9>we`Ul5T zDfqH=3^*0uj{VZ@ssIU3xc-}|qR{32W@sSzr37^T^0+hVb$!-%^K4oGdOj{hd$0d* zu{c^4&_L`3)yzFfx5upv1|Q{($rJD+=uOL!b7G~hv9q`)aJp{ax;GQ#pLfFjxC1h2 z1fGa^chO*fsMOru347~J)RX_a*W4M9PpwTJNV>&`74$&| zV5I=QxHU?ZA(*x1*5^zg&vktGTp2C;;@&8!1l%rJajif0U8Yc*lzO}832r%Z<>ue+ zPoGpTDJTXuXfw8CF6Q(xN4gxOsR1PL_}oe!U1?yfDwzJQ)gsDnJAz{e5>g zpD$OVpp*5!e;mAU1f7ehZ@jI1m5RJ-f+ikiEB0z1yG<-@fTzZy&KFYuh`% z5B_&w0BI3FBVgdS9l_f`g&*$)b2IhPcV8#_z{e8Rp{79MuWEnPQQ!sWtFYxukZBHd z#|WaSEqGE8`OGc++}jC?2*B4kd;vj{)qKrSUj%}V0s~&)%|MXLH^3H6-h>Dr=iQm zKwgAfq0_#W^&U_~;yu0m>W&%Pe~4+Ec;mVDoDN(KKd>G@9oPtgDFmafnG&PLUq ze}ljO<=0lY`F5fXa%}@id?fw@TY?VHM38D51QCVF;I(@8z8np{+8Pb|+CU$?03qN@ ze!#?8A1W-YgD@!Kv)({g|Gx;`f03<#sRz(rBPjkP(BI#FX!u|8@CEM3co+D4aKT?9 zmc0+1JrAwBJQZIl$rN9x09r{4kUSW3QAK>ecGny|P&PtIiQVnj37_ZWZ0lEANi{Sy za=aWgHTXjl{Qs<6pxRlPn*Z{>oel6RplYs7PoJDraPHj8Gac|cg1b4F8Gj<-)CfkH zbl4XTb7*(B=S@0)FFkwKEa-Ac{Ug%o8M3Q;K`m`3DxXyOHGi!A>)3JgYd2M{l~R3IaV+<{T)Rb>?dE)}^;mlxDQ?;O40&_v1i5ciFD;$>*tRtpZ0S{V@^?MS z+nVNRZqjB!>79WYqKrIicXrM@Dc))yo{C(vBsv8lFYD^s$Q z%TFoclcW6=j^yi#ds=<0Q#)VTqRBXIQ>z31-qWH}y{y}UY^tVlFJTC@j_7^<^ZaP- z@88qd+juu8(|f0`^lsC#T)ASi)Dl1abWR-6yKd9!QP}!B{rvo$fvDc1c3w|6a-nt3 z!QD2W3(xPQym*B`WNCIqvv7H3dAWdMuiZPcSj2vXCnuK~3}I<&8o|%MqG@dv%BQ=l zw^PHu<-GR!T1mpN_UnhlPR+7rp|Jgr;5ogn1p`OB#m=QIoIGI5Q$@OT+XGgSPK(Bw z-ST?Nx`X|T^?~*H>SPe>P`B=&f%eN90=qOoq}z&;6$HA)SUmq&1#N!>zViZlK0yM& zv`LW2rsB5W7vg2$4N&A?fj9U9{inIUxzAK%kZ#ut=ux#Gt0BA)0Lga}_0nu(>g%wyuXt00dR6rCqYVa+w+{QP5Ha1Z_Fb8RH%ZW2_QJVf_;s6e&9lzea)Ir>6ZaN}@rl*uLZI-cCyB@4oWO)1*URztkWw|Fl(AW% zH++8thc8xVflx$Pc52>6qDSkcjDu?Osz~lWqIA?)x(HnJ=Z{9{U&rb^%!tsQH37Yg zoQig%7UT5>uV&|YFa`Nx&vf^@)y4nb=`<)of5yISuBBF1*%`Xi-0Z;1*M!4+i@$NE zvPwt*a6k1~5w7}k3&gIkY;FbP2iLezggwfyt-YWj15T8j4R-r@nK|N5Fk8|*)4kMx z_!Cl7vfk#kH9ZBT@dBA(I<$xzFsq&+9$%cH zkRSCV`g0<$9FGKCTb zqw_`WIp>>L{Z|zzE7N9+5Ov&7QpdS|(oGzF;b@dP&#~P?ZGGovTxm6u7(N;0{L;tc z97KsVe50fTU)B{Z-TnjpXINX3@|@a0@}m7|tmUPL*JH*AI^jf}|1OHe7!nzm$f-v=9AqK~{zm;|kxiZ*kir zf7Tc{5Q9o@1Ram1B5@6{z=;x=bryR{X@a=JuIIuu z=7b@$PWJp_yGi=lx~}48gpwOjF{{e&HM`e0gULlGr`U$Th5sGaVaF5jCJ@A~g!gGG z)W|}R`#1s%Og-p{%-y+s3MZc(@N+qr+7L0QZR>l*A+Wh=J^hTaLu^IdjYmgDUrNg$ zCH0LGnmt7`&|#a#alooyY5YWA4l>@SGhS@RcSZ+G5e#{|hs@#7Vh>VEC$)ToQ(G4W zgkjdSKZWa&y>muujm*}D3M-SbjH z{%PRC<-yG#KsT!ANc7ok>QH&3ndrL@FnV%>#Y`9? z;wL{Th|g!y?Wu~Fw&3kydrmFrK`n|n#U51JRA=HJb+c>ZQyFxPlONumWn zK|$>V)b?kq$eeJD`WvxB`5L*SY!tp=28H?K4MDz__u}fm&hq!mZ{k<}I*tSM*ixL3 z?4smBQbC+@2T$+cp$tRb(_I{39zcWks`- zV+)^U73W9HrxyS$>88N zFk%Rn4L5Z2$sq0Dz5$?pD~JdxN{%V`Cf-tSLAfC@k6Wc9sMvtC;JI+?V$&yNv$1c5 zh9BhxM;;bgI5=`wNsrvt>=DTp^M<53067SX-J@rE>?#)N0V^>82S!$yefg}C4vI#Q z_XtH=tBocHl=5E_!nRr2p(Ov+p2%SDwM!}fg1#KLE66;fL0A|J!iS_)79Le40ncb7 z(tBKfg5O6O%n#aTmXk2Lm9M_l?PerG`4V4;eMz~JJ1^fL>DNBnE7)?a+wATis-W9%DsdfqJ@Gc`#~9O%HrWD1|ohH7x4^T98$z^ck20_(qz zP{lY@Z^2sM$8jnT{`l)@>>%jBt09mFd;ORSwPq^L9pc`z%WgQtDYb`{fR~!-Tl^}k zRl)dqLLkf&acLnaap<9%8HN`4KBUyvy8W96>I&`?cBWLS3j@AxrPp)ZahW<^B`#Om zZaQf^rlJAeC<*G&SV0kNdY2gq?A1$?s+}8^lBFWcp4>1fdn@vn3=NX0XeW0vHk9cQ zJsE-pBJ-UkmOkW=NBA&@=$O?x)H2Bx?gt!0!$7rCP#Kwj8-UO2L&`2{RcD|Uul}*h z)i%6p6}uk_jJ4@n2V`Jalr(KqJkabJQh#pGOd%dw^ATtkCMuPZ`gv#E5GTt*ir~zh7 zRsc?dZFH2FoYb%#Z5^g`$cOpfLC9-4$_8s+(zV${!Rjw~x03I4o{r6z{SER*O8g>x zYQnF4C-gECTpa7vJWJ!`ZLBC>PB$162h|S$eN3FTmRKgAFx)2xtGJ5WTMV|r5)(&N zsJ@~q|02%!27&j7g#^-(Wn57VpNa<#lZsbfB!Owu8>Ead?X#h~)p=LB7)zmx)?#Sh zwg#6j;d{ui6X%e&Lq206la(atE$v!DqwjCX z_TZwAA^n9T0g6<(#mXj4!AAw;;0$j!*@Ll|p3H`RRJG|lLMZ?vLRVSxlo%)kxG8dM zLKrq)*#&Tf7&D}+exUXPT|-popdmKK+HDOZzH^;TClVD6Mnao45pU96&u`1l!IK;DiDqu8e~|V z&>`zX?u|;KUelp+9&Ir?vBk4FB8QdE1di^Pjeb|Bj}p`I49yKJPRZ)8!5aG*$B zV7(HqNaz?^d+*29q*@@JlkY0%&bEOUs6|ThiW8|&vZ9h<6<1Z%Qw--bf{zFx zte_LF5Z$ib&*$^C3U5m3VG?6azR;O2(P zAy#2^GuHkTXF1|Q)goV;Hu{8|>>I!hx$U4NT0^zW0Q)!$cQcl!XnVRN@-^!}s~;%K%JLwtUHHZ|uJ1gPF{iHnB;v(B{$xQnIktvEVphhd~w=u*Lq0 zqy)PD`?698U1FzHOcf7$XEma-Qz(N9ylnOvvwMGc)S$z(ou!m{#na+kx=GzXY*6Xw zdL>w?JccHq)&w5L73DYhWyU6`3Mf3hIX9XtNyx$U1hKrpTN{C^bxmd)WPDmA%nB(4 z=xdf5lHfre+Kx7WPxO9DR!xFa!WC(ye(oyb6K^grNeQT17v|G9=%p_EUD>>#tfW?s zQj)va;cpbWgm8}*3E{bRPKcOEqe0GfAxy#dt(x&CLr z$vMivBIMUvEUGi2_jNHH`q;=SdvPY1Jc|?Zd23Pp>5TTP3GqyK74>qwS70rZ4SaKx zeF~w7OY&QADEgFs(=(dQMGxg_LfUGaAulGSZCE^>wHk{Sl3h5yxNY;#>I)~_bZ1l^ zLu>2LfqJa17R6?h6vh#MFb6TinjW-y5UVJW~dnXrg_|4#f5CFiB} z^ZFEXE3nJLa3@u}a}2}eCvn2vd$#f8Ef?Er$6;D; z>0rt-Qu2u%|yQ@Tgi_@@Ramm)UMA5x~$;2QwJnh z-DoZJ)u{gV9!r}TxLNagjjK|#^LwrDr;0sQHX#LMBm9K4%9ZE#lbS`BO-2*|=v>SjD_;U_rpkSdALy1F@twtaW=)PEKoSE* ztDb{KG5R=e_y*qYFec|4N_TaPDwX_S@$D*p-nRPGP?kg8)y_`!S`=Y_i~S&Sd+jS}E&6 zoP8vnJ&Zo%XhTwo(TEehd-aB8M8$^mwNlmbLirLL-c(ADczq_2(|8!3Yqbzj#)@VD z7rWLS_MFpO9oF6%xt~n78hHc`5j#%1TThv$gYZQ6*VJwnf zo=`MZqtHC7(rvF3%aGr#j78tF%!Aoh$vggaq=pG!fUF+PMykwUE z(Pu-eo9SGbtzoo{*ZxF9S>b4f_d5r+7k#0hDSK1tjb3XSvJb=xzTo_igvmjJKj=xt zjA2)(*?%*yD!ePbUtDwM6(*AzoJ+Kk#$O?_!lAFFeB*)xP&rOhiYF(SDekx%JWgk; zV5W1)FU>+nHTWL(21j>zbCK8I z47{Iyo!RPg@TD=cY-N}>(9JPCCdR|71L?upmP))i1R$uZpcptN`V?B23MmQ(i&O3U z6nSWz8WN5%#anPq?tWFuRIEX{tkLM&)M0X+JXd31EHHd~DKqWC%ZwN|9k0=#8fI`n z9wfsD!O@YJlYJwSjA?N)3P8(Bf}iVW*(@an0z+#^S>+%jcr)59c6B?-`lJV;K`<+A z``&?8Fr#NCBGLhZPU3O!X!}%O)7bDD#^4vP5dJZlGY=D{ohgmcH%6ub*)V24qx8Mz zxdhnolTm|9>N*Eb_{u_7m?9F|^mHV8;wQ8a>$cfS#H*isCsc0Q7eu_4)_ZiMWu|fU5&3v)AkfgPAxOxhL#^_L;H}N) z0v?fEA|#=&iO1_NLA zlm)a9WIG=r*0S3Ty^^E{+sIFcpX9#s{}i#EuhDpsy6Lwey*`ktJQ(Wf(P##CEWOY^ zfGr_u^;{QCZUBU+P0pq#ubpu_;;vM*KnE&E#2G59t?GU=X!LCKmLG!< zt4l&8t39Cu#dhcH_Y7v5ufqXbn*wLgSEE*BjbR|cx5r?2mqlywmlCf&0VBp?`zcLW zi26d|Spmy?Ulr}2CHAh=3D)`>R($m*fQpn+`RUZ}T#QZAe}m4ckHYmNn0%(%aNP)( zjknH+%35KcZ&tfTBR}>J9+x-OIoH<-9vDOo|CrrIUmdV0j}@)0UqF!FlzeUkFg>%) z*uO}d5VkqrGh$MrF>YLa9HP1h%mhKbQ`v^yS0T@fZF4i}dK+6ducj@E*Au!t02{HJ9Bgpd5*F0h z;W>Q&Z4~pGwg<;Ii6v}Iob&aI;S-hBc~(RP2gPA;X1{UIuF6z>n@2jN7SqDMU*&pMTi&Nv#j>N|ns<^F^(CoTmiGPH zu+yx5+t?fd2PXN-{zSe(xsXZ7rO=N-^-m}9on5KY`0e7qe?onUK2?lRRz0*|4jXP> zX;3VoRfyk38tM?bMJFJWKCFELG0uW~8$hve&ritjy+N1mFYTZ?F>M(A;Wcm8Bx#Aj zrYNRmz+Wj33M+`(t``f8Da+&opL`sG-PU|{HRKrAwkN5x`_*oSGX`_a&=>#A)xSOO z!<|cNMdJWWg^ez+S{8f1T!(~P+_Pv6hoOtNwO+Xwn!@Y-iCBaSz3*NF>ta~de?!q) zY`UtHmxQEp*|3eGuT%_YD5rvJ{m{X?hv`r~(+{dr@qhkdPW?!zzh~4Ns|6fl!s7-W z7s)0pk*b`C-Fo%CJv;mKX8u+Q_&#}aXs4g7wE(_!x0h>h!oy+pF1c9zNI~YS`&v0D zO{`JUu?`>+)*&^cr;6KsXk)@xz|IBUHqd%v*)gjo@reAocZBvGksK|_>hz2Ad|U4d z>3gB2t|>h@js=zjsT-QqY4J)JQMI;triCVpV5!*ne+=<*+TJ0ltf+447b_$P-jUS>lcDyEps0G@+_D37UB0Z!<~b3Rj^i z5^#$70oXr zB5|h|fIS{M@C&o!?xXgk*|6;CbKs+{f}2{>B!I~ILg>aB;G5+;oc6o1D6A%j%i52( zX9qfpZ1j}C@xMLwbZaO7E%so#6Hbw;h&=?(~$=K`{6xHB^; z^s5GoYBLe0RWL0g!yXJtupB?yf6ex`nprZmcEw!UiiF<-YCeQR>xXu+@sT)vc!>3Z zka5MuiNS8M)t-dX2argnO4_3@3w<^IVEVCZe?R=jJK2jr*=;>@=bxZQFO*GYH)doF z8su^|UVgj^H;g$S)d~O%ff5faFR5KfMW?-cTe|dpMOiH)($2S`rGBs+ounZYQk=&U zZ5c6{WQFt#xdaBQuPL-4m;#P`fKCFV z4n^Y)m?ctuuT_L&jJst3o!G2$^Fj<_c9@JnVVeBAh&n>Rv-Ms=afrfqvJLh^X8-45 zG|QoPcO9$T(FE5~P! z04jrBOl2}7ADl`9Zyq#W#_xRrt!57($I{5J%kflb`B?zx{!4QStLW272I`KJBxP}8 z(Zv*7z#Q8YY^zN&roEL^h3DRb1K+#~w#2!5H*;t+YCK{KAmQqM1aXd;@C0`?Vm`?^ z&%QGhuyWkI$C4FU(p>xp|9nS(7EJ-j@qFh&8ql@fv2-ssTh}pCQ8X#i4U~=#Q2o8h zU=!q6A04BEaxajT0Q0Aw4F-l4Z2fTIn%xNAc^2V(W);PpC~}n8=s-uL>EVZeuj{vW z5tZ!~Pj@iVBTk2*bTr08!k6Z6p@VU4T&mYboDPo!ZV$329 zDsg##wbh~soW*71Io@El&~6c6va5^MWo~j*95l{x%Ofjvl==~=c_$-?d81B_ePtgv8d=4!ZfzpUb(1LURqf7&#eF1 z(Ur7_Z=g*voa%hIsq*A^qK}%^X-t_MrII)Kkpxftg!Nb-wdRGlz4wWO?P$06;9gs_ zm)6^71ix;L7N>bN7!%tJ)rzklC3en3Ng-TUX3D>aZBo`12)*)Jfnlpmo!$>NiPu|7 zuT33sG|r}TaY3Ovt9%CG7|t29ZFqpmqYe>%+yqIC+*}6*O)u(va&6yTeT)&&;pj2n z(xg@?F3QA87;Tj@*1CbRN#frPNVyDT0-0O7{9O6Os9Y+qYfr*~hftk__t=gwM(IIUZsJ4jJ=PSDJ{4=#%Zn4>ndP#ofBvl;|c-!KcdrI&2p?e<{c?_4Xe!r?C zwu6a{|2Z@@iviIMZm5;!QsW6V9j0Q4?-?DMh-J};h(xKb?Wo6d6IOeMgUb&A7DIyI zpve&b;Z!|8s5v{>#ASHdG6TCJ&cq2#LR z-pX=KsAU)AhRFA@lKQpY#32`aE1W&YQYDINeQS<@PSxFx>xCtLBJ!u2WYAc4!>Ga{ zTTA7g7_Yn++EfAfJLXY^mPl?QcUF9HRs7jmSYgF3o5(RHiTmC_NT9+mtIHrU?3*&d zBZpE3Iw-!5dO5wfB9a}_)DB>30YDPp4f%ySHRJ0=Gd%6wz8&fWQrgz>X1r(g}SokQ!E(BApIW6d1Q&Kj|2 zES<~S9fiZeH01DDEyJn;X;Oyj--ngh={%P`!PgJ+B{TLqrybTL;8D9y#0E10eVdGb zzq}N6Awv_wRqrK-F)%#8oJZj#&F!*A?471a<(W`FOTDT`MCG-#3@ky@u+$wvezOg$ zLm21fvDksT4WT>Hf#T?wFbuiatLCXGG#C>m!nI(-==_LV%=^et!FoCfL!-UKweUt> z-QP+s2Ro0$Q2QwIfe;`{ff2 z&zY63=5X*!)YRYW!#Wq%H8)zw}+Z?_OZ`TIYv>YnD1l~-6RZ(g#`Sk zp-c9h?QoDNZ_rRm-LJoyjJglw5kH&eWYOCADFdVeNlBRWS$_Hu*XK2X+*}_TMhT|3 zq`l!i+6D^p&5G7WRc2>GAPbM1WyOA`K%WG8;}hY)IufY9s$U%qs)--Kiy|$iVpKvq z*WKb)lDqwiDsq`<8b@8*$C(A!_RIYihK-wn#_s>;o3H=gP5~q}87*vk@aGU!1Afpj zq)v7Z);%;dQgdwGuk^pn_*1forj&!sQD_P~gURV9*@Jfbs4iELqkK0QzBYuVC+(vG zhxT$cSXCEuhBLwD6t<RXes4E$o!j()9Qnt+^y1jC42*d;(!CkT+H z%6sf2LdBA=>U%0WIq` z8XLW?;8opG@UJyB&(-YGDRF1Y@9$nNk8ftizhXqP*_4bL0rLnj;9>gFk=T$JgR>U0 zvZk|BW#R$9(>z^zu_k|~G3M?Oc|?!%9qJ^0Ql`j^2#?re+y(DkJ-y-bk6uD_kbhR- z5>Jd11oRGvLA)U*Rxhg71tC7vq>bT{jRGr?N5ze`IZB|BTFt7I#6!|sMLVeA`b8r@ zP$KlHvCmE3G-Pf`Cgd&IFA)GjAKC{C0F+hU`^Z~vmAiCcy9(dodoH~YLQ;=8Z~LU* zfY7>jtMRUz(c3*YiSGS#5A1;D+8QqQbCov5^Uup|If5D+*DQ2+qXJz(l52#> zSZF_KdFtB>{AjR$!W;+NXNS(+IHb7)-L>`k6Hcu~n7*n;7_A(AIzH(Wy!o1c@W|KT zgbPYCd{A&jhG*&0j=gab6stJt3#^x;W|D299-@B|Kl}J4*pGj|XLXAMjP#IW1B@>W z&L>|jJ*Y=u!C~NU<}&NSPG0MmvWef!DYwR=3?xHec(!zaw7BjFNKGq_�|^wT|!A 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΄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%0A4U?1{u*l9&NM1aX9{G}}>LcH$=u{|! z`a;ESg<{a9v0Gpl1o^!RAx52C2m|4AS|&!DU!(?Zs?7A-3O}^1;4TVXa`O4QL~+>h zdOZIyKCT2Yls=qk*+=P)`Z14(+3!>Qy(k3EVe1)3q*vjFdXK7KPJpS7ElJ%l;27mPlURyY}OM)3FNE)l=Z&5_z-^`39^ell!w^n}2I6mmKYyOe#{@5W6wWvSnM{ zp)rYV;rH)pRJ=mt`|TqlyF*)`Hy9erzezBp3QUv-m(_Zh)YNl84!p%3gYtkqaY;2H zJ+hB{%VY1GQV;XMkpJmsY_yFb)Lr<0& z4l0d|#U|~NO=$j`u#YCLms2~x)a$7bqk$4qdj#H`z-?nCA)8-77YM0fGcAQZDu_T; z!JV%-iUt}j^xvqF=h>^U7?_Y&;QwV)M<;h4AgWy>X#Dk2LN8lOG4CddS9kOaC+q4* zqS*o9W zP8J)`J!|Rce9Ha&fsrTBfi8}^Zym)#HZB_fxt#b}Vy1o=vzYWUy}#6%Khro^WT_6>tY59qve|JKzcUBmQtC;B&bH zycHh35~Ez?GK3+We@1&=-X1VEVwCUl;e$DfSJ12-+bhwWM{aIZ>>JKf6o#B7>Y?~! z7RMLQxMGL{QP9zv5V!AGpN4&bL5zw*?00*pK1Ds=ZjaO-?!Y^m0W?}dLGPwKc5i8yK1#kHO0$zkFr`EY%Fj ztRe?iktm6-V({CN;sNGadJ_ozOjaB{h)%haV*D)b{EnF!b*D31M|1QDc0ItdgD>gL zxyqo>KD5B!n|M%+VF^d}U^ZS*3SGYtM7;dD1Gy^*SVB$bd?h>{$4|l;l}I??y=B{DwF6tYh?%j72B8 z)jK;xXNzo0dLoB@0J&j5Pvz~W(gPxT^vD*UJ~F_uHKb2hwggijRA!f4>CcvM!Im+vg64 z@hl|L*&PT*eE#-!x4$bAbh$gb0`7oR05}?kJH-@G?~EF+)A=lDE?i0*sq%lRc%5TFKa! zb&R_$~>0tvAj3601g^oO5~;6_otI_knf3OZ!)J2+pWNlP&1WIks_!< zdgzE^6-+EFwjmr`epf^Acg*&U=RI~Dj3L^Jqa){RAHRQE@O~`2bbEY!vnrW9FQ2Uu zMj+69OcN5^A>W^4BLpjOcox>77aGs$7AIt%HXDOtBbqnIipR0$m@* z$?Hzz%|E2$B41TFzVe%L57zWZPbp6wjzV$V7|O8|)Nue90~~)b1Jnoj6c(>zBM=j$ z0JunbZyX8ME;=!l`qP;fL4wJ3fV8qHiF+7us&qi;00w8I@a7`#PmC+Tda}~mmYQKJ zh1*JK<_p(zzIqo1E;c$5haJh*g*;x-l;l1%o4*4S#fS`lpPuZdC{WRzX%O2S*@$RxEV!cZb(quF|dQO|Aynn9%kJS6Q`$8BP- z)IAF5N$yIvlU^?$IFKAK#23n_!ps#0a8>1_NLT=)%x|6^LC&Z6-YemI8jU&FjVcg4 zqu}>afqwFEN<_f8hXU!^k2=%T9-*;KNMzDu%x|It9c`ya_lxK%22w#F-@6Ij4kB1C zGm+&grakmVssK=|F!g;%1!+9nouUq&6&ECjhNvT&x=3DYaJXZ!zyr%uDg94seRu-JKtYLz z{pMe@=>V{_BN!Tv3f=;q&WrIC(tJa5$@$5RL~~fMw{I}7@F`msl6e7x$H`YHFuF43 z2TOwdiWza=1e(TE4ZD~_W+Wxjg4|Ay>4t=Kf+mWryT#_Wt7EXIMWA=bftv6DY(1Sk z_9$-DRC1KA$#Iys#z|gaJeyJyc0ab+$x(VefOT&OzyO#kbSiBSrp}9pwC-ZS`dejUkFUQb2z7FS9*c=hw%N9DKfL$;; zCJl1V)HRe1VP0=q7$X2XmF6gy3zb;G)TPM?b$mW;Wjw}Yk?Qz{p00wSo&lC6)ud#i z&ok5y(sQO4+wDU}q(xF=*65+JU1VLlB&3bcBR^6bjQ59y_BG5{9RA1ikrEPrj5j7TIp% zPKzjhPfy_Dj|^_Y6F9L8=5Yq$>LP2vzq=8A4+gkV=*)_*AuNvw#yO#(5_= z@1w#%P_B|Felsb$m;0*%lV*EHpvwGj1qo=JMkJ&g7R!_fk0PD1EYIc<4<-5uZH6_d z9!CdJRmccEOK(73W`~xL)apMtVYFFHbDYCXDQj4 zK@E($2Q0qsfua*Fa9X46qvBi=U*G?~;E|>qE0BO;$rPO|+!*R!(xAiaBv>*^mH7P< z+mF2u^ARpYv)ObkNhM!tfXT+Zx0$9k?wW|SgU&0 z-$c9GHZ}cl2%X8S)D*ILAQ_{FEy{4kV2q&-IvWngUs2qYfB_e>k|%uu;|Kz?N0mwx zOJ>>JAw?6qSSPVB*k>+{sL&E@Ro)>1&tIj0({b6RtVIjWY;9nD&j7v`kjp?XV{4%( zIzc!n=CQq5%BCa43_yVuQ$P<;mNf+nk}f<&&$_io5Sa}CP}vx8j`(Vl z!n!w&;eFE+dq!j%D&%N$stVMd05l;@5JoJ-A*GFLp@9o!VgzGDVMvGh4OGg*BT3ed zGwO+f@S&QMuJ)2cJ`=zh&NH5M${oNvx6^h&)9LX{dJkUQDBasBA!fQ_rmiF}a(!xI zY*@@p`Jz*ITJ?sEvQe5ad{7u{-&nlF;Ecd#IweYFs76NKcZSu=Rpz~L$I zy=Njzt0vo#Vd7#sMWxb0kgD%Ro}FEDVI}x|4uPLvDIM8>yjfIwWWXI!l&%>^AUPIU zEkxs#eU2uOi&W-=6&avBT#Bzr*0nfkXGQoUgOt`SAYrJHVNI^WFE#7{Lnld6@0Nh! zdLxKd)(Cbn&W{)QKuRJ7)}#%JmPOVXYK#lARUXnCh055| zsnLVjE}>Vi1?ILDyPHdcz&FMPt<$LStfuV3&WYbzD)69EHk! zcqI(usmgK)bde1sOG=jv$ViQCPS`%|Y9bF^Kb}pkZE{UEP73${Q9!Q02c?ntTKb4r zqS4>-+QvBHur!^I0`>*RBsxh=P59^mhc8Jh=$a51)S=FS9Rp$xZBNnYj1L`aBE}4! zr54BXL(;Ltama0q({47RnuDuSC25G;Ov`$ZwL;@$vr;iWPjJo0NfnX%J0T0kFfk~j zPg!i`%9TP-Y7e}*zyn0`V4BTbNTPhOF@ZTA8%ySxB;OfP6kHO49~M&-tpIXINe$7Ey0{F_iIYR2 z9dgWZVHl%Vl7Zyd#3<9oN>=Q0_Z6*CwnZ4&yfK-R^Keut{>`G>8bOK!??9@AyGGF{ zWLFUBXJbJ%#opM1{)2>a_zHx$@%&F}cL70|mQBOB|xx+<@_%wBJ3~`kJR3mR?D62v<-gr==ye6J# z;030}c+mlws%-HgoVvtGH#amfz9$oni_~l*JD6S%@6?Z`mK2xmn-D=%gPED8-U(T$ zNk<%|I(dyE`QmD%1JQ%coEuuJ-m*$@726XZhAyC{ewreDmep+*Ezz4C#X6CJSW>4n%P&0-n(Vp&>islg80FMY@1I1j=C0_iDsf%TN&+daP;-@iuD_ae|~b zk}ol-up-@>12h01=c61-Me?3k4R_&EW8)*A-q9mP>NHSQY`TTUh7{zQu8m!TT`(qN zs3?fb2c5K=sv}8wUv+s0k?CT~)SXprVSbi1qn^>TPh_n@I$EoGEhg<9g&?n&6% z-`NiRhkc>$Y&+nUemPdCY7NOR+`Xl56TR$|6}GSM+R`OVOdt=`rg_g|8y(MQP$^2! zo^YZmPkJ)DTy+kRNuyR0?E+y#?LqMbxL1eJ(}|k`Pne-LO4}$wW!wPgWgW17CaLyU z)5!!)7O3?aAoc8oI4%0z2&`N2vut)61>@P&I6AR{51Fjgq=GzWLZ_PhmT8AXIv`~> zNPMX@HI6qoju)&}I(e!^G35*@%6%rP9UL1@vva;UI|QaexKdj)ya7h+3_(o&B{XqN=fb)19*6WdnRXv@|Xw|xTs~Ju%o|2 z;MZCN?Xg2PugpYhZwghm>Jsdo#@S)NqWNG)Zh2KzlJ<$*2ww1ELKDa0eAE*3^f)^) zMzOZ)Z6vpw_&U+N3Nm6s1B)m6Dtv;bx#8%KU)S`uejqRdXp8UxH@3K8BU9tcp_E;Wc`hKHizAhoz-su?8BEI&V? znM-+D5YtAZ8C5eNuBC80Voe}lWs}Uz8aLt?GdN)4CmGnA93NNP3sQ>@Kn4quna$I0C>@ikVST; zkye04CIZ{<(&gKH^BI0ru5ns~F^DKy;VREO1VT@JXzt{AtN`hp9I_F)u?pZ7)s~;G z1yPpPu?__Zs-c-7N8Vy8*0JIkv_u!TP?J-B`o}s*2R%!}q5~zLpf-xQBI&t1Kj)lC zQI?)tF2J}0pkunq)Th;Gxgw=g)+npu%s3($SI`-=j1{p>NR8tWI*bM@uigOEjDWs8 zumz0V2>do4)eS4T%rj|;Oy%B_8UPs#V6RnhogA@A1yF{iRbkuE^hTz;8$)_YSr1%= zEd<+&$N7U=U&m1idq8gpvKB!xjY;4g6Is8D?Md$SINruHFq$suLD0h50gYsH47@wS zEGuO5Qe@fMXr5x55=)OCWV0vN*PG52GmvGK0?LEz%mmu`Fe_8^Cq;jcMNyUzSsjRP z<>sUwqAi$%w^5{j4q+=@1yT;J1n;;|(WXsX5VNHs^iWJ)`*@mN2A0&xnAr^L>s&U1 z4*oVdaSz5j&nkWGklaNm2KC58vPJDcPZr`ZtPHwPl$D+yX6Dod_QZM82OW#7q9~RU zl&y>xYcUa1B)ecoNpR84yWIU$EHh{B~-mzsz=dxMG=#5ejX&h%cuq9 zs>wXi+-M65EbLeymr*?ot8<1`IeF#fgBN=DO`x7}1g;Zp%x@|t>xi?XqBt&$(0dA) ziAr@of{@rj)6nw+=i9TfOmtiV$fft}8C85J;8N!|=XyF@;6+)DEjXzdHx@0B6t}SS z8WC#yGLGVXq$G7yG`m;e{^(lhJTxK6;QzxgjcT4V`Om|e{Nen3Vt*G8aK^_xhTGq_YJ$hJh~bbhKaqe>*gIKx7ns4AZcEER?%|1mSH z9B)!?fr*Naw%`TRnUtbo{H7aM1e$hOnctlBcnh9rY=jY=S@Y>}>W~2BOj@u7WQG3p zj9yssM$X3Q z7AZq`+-`F!NL9EG33>+gQ^MqNga0Qo^_rh-OvRsh|2e*f0U#-0vj(NgF?n3E&mn#eja$DK`~69ASDOdj=$ zfVx_|WP+41!969k>TSi2cxZGDV9s;hRH;G- zMK}Nw(;g-OCz$dCg&MB(27W4;9cgB%Z@4aCrDj}(=I$7BjjSu|eVdv64Ae7D(7#&; z-ZEC*FkyyCqwH!0?E_`@kr|2;%JI^B$--FNuUs!2lP^B0q4PiOc}J&`>jgX@QrkK0 zr=~v41=xTbFFqquKU=_*D$c-8zCKBu#!Xw`RO}7Zw=s=!j8xNL8b$I9WdMXFYX!H% z1-xlOu77}=Uc{4on1>cB^}~ff5*-(txYhm`q+uP+=&5d8 z)KsT3p_oYF`9278SVF#UNu?4r07TS9GPl(fXOgXE|&bqS8HYX8kG-P>PL!`W^_^7NycDdt!7V z85gL__-LMkAN9crb?1RM8-(TQiQIC5Mc`(JB$6NLZuKz_JC`T`)EaE+CN1soEh80$?nVz&(n9U_UxK4rnREjqX~6HI0*Js^GbXbV~RZ zA)QI?Ndl^T7b-du%>o)jC(Z$s2jdT^2QW+<%VGWw*>BDa!MEg=2@%#gXXd>xH!Gc{ z16fvjd1H2Yvm$)6$2ZjpNjWKTPBG~dgVPM zcn2C)SIeo59YbPv_)2B%Qv7wQkaj5Z)79JABGt78&)pNrJ!=2KyniJjRA$K15X;w` z<7$h(3BDflbzt(cVAiKp-@{&2W-(RkL3MJh><5Vtn?Y3$HGDP|9nX%Wb9Ou$hlxbf zRA$4AMR_g2(WXM6uGxNz87qiZb7*AE>BuAwRz4Q+o^-5EXUuFwxZwaZ`cB|A|# zpww>q;E*J*4$%vjYKw*zRM#mVExZ(OwxCF!+Id1-9tMv&&1`Cn=QYuvW@p)|gFrUV z4obb*`YpM82wI7cq3*t5aq=cQq&s&sG>L%X7}LhKXKBbht(&mz=uk5!F`!WiNZ!!B zX;tEgI2td!k(;-SfqxUDS$^A;I~KEHm=av<$7ydior@RHLo`T7L9 z_@cJ+qT*ef=iv)#%4g}BFSjO_F086qFKIa!Yz0>Sr1`ZjZo;t%2()Qr5(^XAt4d;=78`TV0r{dn=W09Xxd|0`S8X1gGg3|+NP=e4b7kG=w*FWEegEB z`l#dbu`vvcJe}}Dh}zW#eM$5e4J=OfOlnkBfUb$8T8~SpOUQxX*G#RQ$J67IsW_`m zvLeB;YoWC^3j;l!Yk~1Nb2+Oo0*IK|t*GlOQh>uN^cc~aG#`r7B8dT#FMMhwQrWDP zP9MFwiI%AJnhQfU`SAJeF%~6{K4A^2G8|q8=1s&)^{Ytz{5~nw_DuaU@R1Fzl=X;b zjgnagGr-6edmqW-O!fw-u7bT`k#F@vaHD_JP`y^4BrC&L4*mFL25FJZj5_m2zsT>Kng-godhF`i;HgZLd`$ zNu|A9bgwA+iJ@I&YnPertExsPJxN(NMJ<8Udzj4l{m1yx3sZG!2ZDc?AznU=WTe|n z?TVQJ26e?ank?{oPfbwx3S&kyOae;F7xWbOI0#QiotrSqOPQWJOKubL>zDaI?jx0| z>R1>us(m{t{Y^`Lgg^YuR3E~wX%)_Z$Yabf_6wQEtf2NT&rNoiWTKDcJ+Iom_c(gfVmYF}mHQ3-mHK ztvwHzaec$cIB4OsxJtNnX>_>A_EDR}G&PRKS7hi2^zv{bwH?4qPK3*97FSY1NinR zK+B`AA6dlAhhXJP14!cos|u(98sSFAv*JJwl`!gMJQ^JaVhJEl>TC>w9WySkQF>-+ zE~OQ$T8e7l=zcEY!|g4@7tH%MGDcIMhw;nsQ=Dzl@si{#$vTm$mpYXY_ws^g@V)FH zXM&qkOQnXR8I>IhYSf3*xm?7Yl!V0rWZTaN6bX9rf^UY{y)B#QVOoqcN{JAu>n$_Z+N~b^b^0LB-I?r(k*=$^ygk~XrAeL24is~~({RNH40=rU`kWfF2 zj>omF%&`Bemv#topwM}}*F0y^xrFL^3RZFSRc<5D3rY5$qB zR*9QQFUX40nPx_!U+T+5YRZe_)A31qN=dt@x=XDg zn@UhLG|2$&eFB|UBw(czCz}uF#^i7&nmOpi0Ad5&6`r$`Ul(Xq`4%-Z(N?d|RTBk^ti-dNAx?8emARr_Mz zOelG7S37>($(`r9d!e@W&fMUteLmL#Os@>NOT9pT^)p3LmH(>wFSY;QI_f{o{&&0m zFvVK>@Akbz|4+@QhLBnCbuWKB1pf^1Z^iRJzV9CRerR<+)j^)&C?^-6IB^1h#b^l#Zkr8HO_nm~ie%dPXobiEAMszi#n!Nj4o3S4{y-_!h7@NqFxgHy7 zB}cArB9^)ZO~kqLLHzaiN#cC;Vfbb2C#^fGJDNyk-F(P(&c?K3#2J`_KaLXTiNy#% z58&rEW70ju`I?>Q-PFNdOCI%oCwc-e!$-~b-pL+A0o;E#E_)^F)Mp{v-zm*()i6?5T7!`X}P)wkZ4xvGiO zwnmp;4PVZW{Q+uiy>9k3`0$JOU=#mwGba6b{NFKY32in05GEbjcP*B@#QXo zMS#Da)kF-&_2yYmnf291((n*jZ(d(>#cv*1Z*HiWyNdMv@xT%NVNwCZ+-i8~=TM~Y zr{9`qXd<&(ztj-HiaM8_-$eAr<7Czy-zQK--L1z--`KhDdFVLNt$%4_HQ7Oq?SrYJ zlP^tZ&0Mw^{FelXW=iwmJaenqBHYuap9$Q`zqc2KgGIMYT99uO{BVr7(+24kXSr3!eoAoi=GQU|rq{A)qjA=J+ndVBzaiX`v?yvbV?99I2 zhg%H&ko~}iS3|XR`f**u<<@et_r8T^${EPiGL=NLN?D9tm~$?150XKM?eKd>z3Ka(*QW!qmKCt(FcB2xdMKF`AgjGT~?01C&%gFP3$@G8oggAj$UtO!oEmUDh5C3PAZoJ-D zM_l9S%n~x}4u*Z9U<=uZK3rPJ{tVuqOpk}iQ7N2(u=XahL}+Tk;r>tHgni*)&=>GE z&nD*tLf(*nHaXMh3(O{Vmv=T<>vsj=uQ%YDO>C1yccwoOY9e-z8xjMa@NDAn2G|4 zy^!j;U03gK=BZAf50J-V*HNh5HBV>v`fnp=hQppFtRC73crL|u;SaXk>~o*4-vsT1 z0E36aUZ`MEaFVPIhr(-Mz4*dVSAF=mge-zuogrVdPIr3XHtdT(@LA}~s2*zcUJ6Y^ z`%bKuEcUIzcWQ!P?q;1c;EBVU0#XK}^%EU*!VeU}=PK8ediNSaY}jRdS^TB9{T9m~ z(K&pq|3;ky`wu-oiano%cMgFty3APJMC!depbl@FPPf>96hT~i?1gSI^xy9H0__Ti z#tpi991a`yE`aSV4m_rFdf^pl-x^=U+*2%>8svdHlI+&V(7hV^B!i)JIs(`6`pq#8X(6J4?sH4lE zKJdkIo$cFYy6VUE&XD(}GU$U3C*h$Aef3e8@+K1jNx=Q*irN*UmMiurGr5WA=s>SU z_kk6wE0Ol-j#?Y;(U%h|ppo14HP!2Xy!@$WYN{KaZd^fH&wgdWQ&qLC&)WVlURCRK zJCTlm?>&D+%KgMu`0(#L9><5hF{JZ<`8EEneH=5sz4ZyqxFd>5zPs=*MK-OshyT<> zbjQvupq>BI_NN)q*e~BQGq^8&qd1&Ii{B=6*v0GVhyM&fl_g4*yZpiD5uZ;-XJ7Q+ z``Ksf){39{!QmhOXjkXs)6s1`9mko|S)+!|GPwRHSl_PH8LGP#=1%AIKn;#&u%@H8!oq+NjtVyMm*4NIXMxLYX5yv zDj9KwLheY=WAF64Lw29X-))a{`GfYb&)4p5kFoF-GGXaC;pJ34A3c}kfYW+pMm|p+X8#t7%|Q#{l*vdNDW?^vk!Lt zKJs9t_COJD7N*b|y;jEm=Rq`J_P{H!hZC<@v=4MnsnjKcJcvXZDmEn zj{Xk2Zm2<6d!{f~ASYkKXJu0U5 z(>^R`jZ0f+=|i4CWtnRtV6sIsD>p?@@*Lt~qFk$M+3n#TLib0e09r2Y9nBw!Gq(XhgdHoE2Eyv$b#^tWNGg}gc#ln z)N4aJnUWk)4~W@+==3{C8=53sLXPR&Vj?;m_rzRKUoJBtUPv|%p&``|bseJv6T^pf zwb>A{y-!En!vWXT#P~;Dz5B3k;gX7mwYp_?@qoV0K31*YM{Hjp<+`Y@>`UYd>8j-y zNqK8{IQB)ds&>mCb+wT{>TFl(jp48>lpwah=@(k}kQaD>DKXBRljc6Jw_T#s)w&ny zjhE=^g9pf>r4y&w)F$o3I%!xk?0c8abQ4+O z3w(-{nT)sXn@Gm?0%6$e$ZavzIeaG5PLuw61Nj80&7_I#6Htpg8vF#Q^L&idu3trL zujp{n#`X37S77f~G>q;dmgB@N2I4!3={W2<|8Zh7Z7_@3_B}90&k}&iiNy9-Qe)et zuc`4b(iy&~YprOAzKc{?{!m zFgA3hVArNoc+|fwnn^~7M{hBfyQ3lTe4X)U23wbL(MzPEYsX+$??6vq@6cI2gG1HC ze74T=tj--1gBfCaR=2?Y7hRqEM>=mqWMGat)|o~l^0dj)OX?Dr8%@2$>NU(e|IspU z%lQq1~||SY9`@ zix?gxozYAt`m^#gVN?Ctd`~Po9*to**tG(zDPS?|u9nku4e`V+2HR;mv#rOtM0Yp2 zwI8o$M911QdnTfK+Z{yjjQj5(c6TD^i4fBrWR=@(tFRrYJjXO&e>d#E2Fda5K9g;! z-n=RvT&iE-`yOe7-M{2);ypxkM=X*6@SOE_J<~{>JNc{UH5!SP_ujA3m;J(G zZ6eM`o=4XHU9UZW>V?#-2a)wZ{2Zpe+we<#xD*wI&i0ovY1wyvg-Jj889o?MIaur5 zlf{QejSu4ksYMB4Zy`%hzWVTt)O8=aV`{i>&u7)WcFXUy8eNIkTlRL5503D5m>$1h z=Fji=#g8d}tmXf;@&Vy|^Gx~mFMV_F->_ck`-p{1skc8%rAI^9)h3z$K5U`Uk?AZ({NuXCny>`9ri)2wA zi3Sod9f@8Lc$4%wc8ch;+xzC}vm5xl>xuFGhI|^mDi%29^tobzXByJHD&afFT!JiH zd&$b-;7JnYmUu9F9$Dy~mMU)${c+dBCbEOvt|iP4B+M&=o=*_#X}XehxgjQAtuwAL z!teT3G4Cv+M48)abQobg~31KBPK{dYjOEWq9$6C{PC#CCyJN{9P zhBA-E$&~u9U)$I-(qDxAkxf1~uhE&=L6$|wxW>gl{jV3*T;q37uWAOaaq$k5h8^p{ zbMuD&#lSi~i%R3xKP4)WbqxH&(nKm7JaZ>W>%&(+i%A_D{z?y}gkpzMsV`?<#+Ug+ zQFWU?>~pz19*;c|L3Nui7_o=Lo^E^C>+giTV5B>8Y7V75exJwp&Y{#h>b7^(ZBwh; z`cU0=)LPT_wPT~lk6P>hc+{$YZB9p5w<{9y`R#7M*K7B=;ZG#c)n#w*2*H1mus_fd zI%>7S-ZflcwH>wYhOAcF{^Yb-$Plx{fm7~@>|MIWb;KdRicZ^93 ztLK-{;9WbvP=oi=Dn*0m3cIEg5h8Ihmbgoj5FVNTPgLMlTt?1{1^uD7UWHfnK3zog z#KOf@cvTBaO9*1HKtj-O5IrC@O(P<#h>DMpH!33>MrqKO@P_{BLPEu)VRIZvfcwqK z301G?HVntbV4jdrd7NwzW3KQi7Zc2zV+n6KaK6sC-BemysCZTvi3Nk+3^6^SFRjUQ z`utvlb;bfi*~*w_YI&iH$qOw(|L_#z!jeQHLQHWK7u-d~1-CEeeGf4X;)AfzJDnoW zxN|rrilHA6jV{kMuR${NAT~jpTLZNb8o?n?}jkx z>cjZgaWPsIo&O8F?kJh%JpUNg1ETRjt<$ ~NHY!iV2}2_Ht!apS|6_h8YFqp6^? zlA0C%q~C)XukOO6piF>8MlG1Tc@Cfgk~rnX4z#H)AI)IWPi&6Tzv zSJ}(|P_A2ES@qu*+f~&B09tm6{#bDM&*p`muauep%L++-#`l$*PLv~df~TPkiEw!M z%qsYKQBC5GrMjQ$%I>VN_0`R@oL!@DsI0n5e>PR=0IE3Ox~Osw7MdM_B+oS!#z*k! z3PZRKzAlT1{zTwgR@0=xcEIX}6yF9spc#j`t?`rBjTTEa{5r9%dhThsp5b?W^>JI} zIcE5Ey7ifAkZ9r8Izyty^dSl$McZc)>5_*p6jtgfry2qD@~6sg@lCw>>ZA-*5h~_v2;Sd$MYrp=`(K^ z_<$U-%=ZG=p{1rf%eXiWP0ro`ux>7VyF$OzLE5LFIuMnAfMu#}LOU#(>zBL^?LL0k zXZU+vsJ+wE?eDgGgMlu)FVf++hdRRnyT3EyZg0oq`F5clSq$4@-*BxTn2WZ*0laY@5f&`*3__Y*|Db9*MG8Z-ZI#AO=!j1^Xz&QYd%na48QLB z(Q{~^_t|A%G&B*Nv1z{Tx++uKvmdIeke=S67GuB#eq^?N?s^Bepddj>Pwp1yX{R@=J8h*rN&_ls26Gf~^$SwBLs zFH!mL!xw!Fll<4xn)iMjA3k^~K3H2nfe(M_L*Ti;rJZ>O?UJ8rY2A4GC(%@Sw~^ze zbsuKd&aEH$>y;omxb?sNRI^{{t48hKei79 zY5Gw-q2+&ea|_Xze*aMQ-MYe)jvuuzo6(8LuKkTg;Z%mnZxek`DZAurYOkDk|NlX| zd-E^{Mgrv+a>>U=Qp`s za!rs_n@BC1CAWWlO*5J$KWT92m|3!OJKgh-KKK;wjIOUejXT42%XQSOf5B}ZEv@gl z`JtD+_>zArs_$|8Is$;GJ$As00g$5I?e#J&8kFC5IQN`8ummn|jvImKM_`mS) zwjUrWc|TJAT4&!*Olo}){|djyj2k!p8)mH7hDp!fkAIK-5i`zBUWyrKqYPo|w^g+v z{_MBaKiO~7zcwe(=?aHnS=vKBx8Lpyg}Ut#Pq)h+inO}|VSlLI9d7TpQH@hGu(-Bu zL#X0~@+!`2_OZS6;y>NpxZS+Xm69_6Db4LFNDBvxzy;kj2}TRQqydz1359KvKn{_2 z=(fIS7^b89jIPg|P8&3IT7sJCxzKyI=>ypB=b!x!?f>`!G9_IPm$7H0 z>j=A|Y$`j6r;e?rwf^tF-cABFd9jnWllVsoI|-E0{h?_sB~ak?of1n4v}26B|5=6- z!#>Z+8%nGU4_|?5(8YO%5+PS$8Z9VU84gq$-lP^Zc51YsAwSgeR#-E}^Q;*wj^o;K z#S;Gtd&Y_do(FYPn=-oN@o7vMTRi^ZlQf!GI&A?`2Gu7AZBxS|S8L1j{p{uui zDx(RvC**k#fnQBaM1O>sm+2QyY0lW-3jI)LD$s%+vDCF4wph&|%D4ovtjYm*9+G@V<(I!&4!o&+&~5%tFAxxSoM|7!@k$8w$GO>EZ3Lm)|FR1Qn7j1 z7mB%VF`8~O0qk1qOJxf^zc86UVuq(bw0K>yODb%>>c#N1y%nAwtM2dddOX}Lio9&K z^;mR}S=Hk83?Cry>k4N)@mTc<532tju7QML)ha7|o!ADAf4P<_EulA6AE~y?t%hF< zjn-;&ht=|}>@ItdGuA72|Gc1X64sKE6-8#!u%v-Y<_@us4X58uz9kEp3@Rdl}8Y=c4v0P)@ zW?WJJRfFzjqwO*?vA$l8$CiBwpWk!DvfrEV1veW^KR56r%c!*)^DnV}trA6>@{g41 zpEts`(A5rq-Drd=&MI33`OB;ytHy&$S0e7Jz+aa|Vq(yLNg1Bjt}AmxN^n7t9af$d z6aDVn@m%%94(sX~%Jv+wEZUs#1p@AMdeaknJgZz>hi8@K7PG#wn%xn?!%FC${|S@n zJUngmMG`(=9ESE`>BtgZBH%wwXNBMEH$Y~X9#skpqtz8HZnx(Qe4!(2A!BY843HW4 zS>S1F?uYA)8K#Bh?>E|hS}_N5*H+zcS?JkpFxMJw$L4Ob z8O#*dK~B{A(OTPWmc@{~W2MW>%0nKg#KYiYb59Fpa+DiBe7)NLG z;o5CI-Fno5h7(YJw)s&ja*oE~D$^_@>m56_X6`m?^Sw$+Oi?;kB1+@ z0!M5|mR)5F%_X)c>i~r;fI=?FjrqnA&~Ls|Fzu*=Unh1nxMJIu8gDT&%CM|{RWORz zRREE><}F&_=fq%Hx9x$`NaYU+RJ6?eg9fCqOLPFT(3qKL+H62-dhqlmkZ_vu?*fv} zs=)>D^qJFL-<)6Bpf|hb)uCb6F?K*w^H^}rdqJr9Q{9Vejx5u)&e`|Z@-=$vk!7tU zj5Z~GJLc{}Z%@uuYfuGY=^CQCiL>$HS{FKiavIj-!{+%>d^n5hGrmc!ywbX1O!~-m zm~`joFzIn0x{z{OsAUIv0RPVZJvwb8@M_De)}Of4&`t~uub<{7>vuhNk@4Ol?$+jd zn5^`}Wmg$zVy!?v?ljE=ZqA6iDBRoW{$?pT{sS+?-t|_TdlZ-BXYOz1RG*u?dhG+} z;Crvx{p5xC{nQy`N;&>JR`!f?Ji>n2DxaI|D?B%mYR9+TtdhB(p)&W2ORfU0;wtjl z0-3uT1NI(BXZB{Dn^Bel*>dmJ9!Fv>Ikw2T4PC^hQ(0%bvww7APY?Xsys;nSeuxLw zi7AmqUZP@qQz^;ZLn`~JVBSfdJ53SHqdreO|8T`Stze#+;u5MWhH|-kD!Du+xj^UH8JQ;)1y%Zr??$yU5Dn=q?micabZHdIy-?a)Yh|g`Az_{gM>FolEhz z6_?^KDU{LwsMEJF89iJ?M)#Bd9U6$H;=}1l5Ni_2(YuIYwbv)!MHU3_A~pN2&<~>w zY9CMO4R>;R-mGWx{F5NhUqh;%(rt*lT;Zp5^`0kn3x$e?r}YEFnPhy=Js^{ka**zS zfzo}o0i^pIh^>WG>;9&DL5EI))2S$p>NK87Wxu&{H|{dnUelkhyFpLBs;`ZFRc{+M=+91gy>awQah?v%R0~uA6NakibdiMD z9Y1I=J^~c^09oX$XgH{=aJl`lgSuJ%N!=9{FezLaaD*!ZDl34OX&6~W%0XuLt^%3e z7qGJfm%ke}$HiE{wL@pxXT{W({t06Rp@Mq6VW@8`nftVF=x5{LMAm^%3-;C6M^l-*r|Woi&0Tzx%p)? zsn@M?wKVHN!u0wsF`C?lRc@bMZ#%8xz4|3OM}_-mq|P;HF#n7!@c)$5*hh4S#f{Mv zNYZ=EX7Un1cs7t#-uMT~7J5EVcC@KMOxd>%G&BnpMA*_-K{A=NeM?`%ilYQJ(bf8j zEA{%jbyZg5hN#aKxJPH3FrQx6kgfn^X1fW*p(Esf^EKyR)t9XTDbBdSM|4yOf11=B zI?Dp6(s;3@{_w>X}A3wx_8zgOuA`eO99gykHI zq;2|wg=?F>OHkY7k11z`%UaHV-O^8$O}(`SwXTWWZ!oSPwp@h~rcq4XU^7#{C)Ht=T_?sh*wxaIZ=>q2)R?u`%=yGXs+fJ&t*9sGRSTGJBrhiMO^OBOlydu?%675^#{Kv(X~X{&r^|Qtk)Xnj3a;v^?&F5@!-EQxSptVvU*liE_JG<=RFv!;)e}}t0RO+59 zRbl*m{!CODug+Ig7%!U?6~=uS{~F1>KjihhizqSbvJ+9>zhd?*Jaq6buSL>V zz7|Q}@xM|6NNHlvXX-Gc`^)(7&E>Q4;eXtifB)V1*K{9dEFYdjt$b6Mbn`RRr1w>N z)$dk4y%SLPzXR8&Lk)2dJ`=|I@)h&toPTt+B$0KUpt-8F^Icgv)J#WHM19P^T zI3*U!#AKZHR#>@s^Q~O0$H_w9>&8=UnOq<2GOjA^m?7j3dVXk{(lLYECkF2zC+TF> zxHIa7iJXx~x6L8H-y14noxBRoTl&xv1g$bknJ2df{qZ}Zf|V+(YBOTTp`u!ysqzoH?MKKjr{s58{R;KRk=!AMKan;)cJ z8a_+oE&bv<`0(}b(|AjPhw$%(k><9wePT1m)u%*tF%5O8uwHV9Sz~aaRJtw_szww(3u| ziUIh#${h=M@6(w~Mr)M?EkoL>cSYi1(ff+U_`yP>Gv z?~-rNw~;;)bKH|3A!XJ|cHI5Pr|+HevcClP>Z|w72=3UQwcean$LDXC^;b%taARoj zQd|#jxA-W3T~KxzzV{i9uU?Pe_fC*0^$Fja&7N^TAnX@rPZb|Us{PMJ<@I2o!`Bsd zyX{^tUf}QQ?6!v@p?15sv%5Rg?g@IjJdsl*ue$^9L=k&OUVleke>3q>Zu)xYauC^H z`Tu~(j+cVpq{trj%pg9B$1TQAjmVCdQamx=KSy9+5I8wueN{AG=z4wS@N^f7b+x`l zdgGhAk#cI}b<3oo!7ILLXR4T=|tFmikwZSgx{dGpc6XSpUBr!h;_b2x|*^wI(%0d-u!U7eMc-;+RiDj zLD?9J*A53P#yyzlH@~mk)LKsOq}U#`+3`Y3Bo_2}QJ@VCN__ap zLh2RrC+O;>_2zlh6XY^BL__n+>umsWPpx?8>F|A-?Zli; z^0W?qdaQr60%)-6R;=#C4(p=RsrCZeta`>weubIKt!Gxl*LJH1VFJcq+saza@auHr ztJP+AmE|<->ZMha*u%Ns9hG z7||al>n-2?;I)T|@cLe$p2zf4{z;RMai# zC(dtfV?othBW)kVXz%kN?Z$2%X#M;9_>V6g;6Gd+!m#i20qFW8JSlLL|JeK~{^Nzu z;SbiM_%5iLv@8hUWP*abTfCkikm%0p#gMTbAU$_jOx$MfSal7m0Y5N{F7dJ| zdatW`winVS=b)R@W9S{ge|W)1`e6E9H&(Xcia)%-h3dQLg_XuvbN~{pnpX*5C$>XV zlIHGM^&;EX1H`ht8h*|vy+nU{wRyk_4+F50ywUg4+j55&_;BF?QR6zh!wcpkI*tLF zH`mz0bxW{2=Kras{sVf}LjI@T1qI^4PwFc_p*P>-qlRF|E0{B>rz+-EuYdjgijU2! zHtx0(C#;OBin{qtM5x#OzS_2XMVT>Vb)sWVi}6;gb8#jAajOLpi+&?M0<-?>Ui>jn z=N#O^XJJJGf56;*f0U=#&&MC-Hs@UzN;7pW{~qeEAdJM_-07x28nCA`d!R`Rx^%{=Q$JOA-e5Pv|aU$pa-P$&QKVmG!_-^U+c z?dLy?+jzCP3wgC4{t)lw4IkxMacS`xK205M8k{eDh6DfQ>olJ4f8pbLgY%0&=hbfg z6?+rs1CQg6hi13xZoa<17IxNbbTvGOhW`ED`RJ9?`P4;N$5*IDz?J%=6ls42liX+o z(0WDeQ<(I>^!Wd$6t&N)`ZOke9{mbC7hjD@pR{}ilU_WH^{{pDKThBX-m7<>cN~-M zFtk2cOKyUVey`p*Zg6_fG^m32ptZ38maaHOofa(yIL`N?vqgWx*3 zm&|hBr@yt#0?*F1CjOqgtbB|vK9i1`(b+SIKkhX-fB#L|uFmU$043oc9{QI{cYahBlq%Z zZ-0pYXnvIasQ-WLy<2P~S#}`Cndy0Prl!VvuSX+A_lPrO56NOxvDj7F#Tq5aWL2v8 z8fLN|(`bi+8Ifc(Gb6I&!AE=L)h@7*U>K5i^<%;N&;t6iu>w}FvAl-$VZaLmw#Tqx z$cDYZ8U{R&y=%i?T1hMUJnp@5B|2oO92;_uO;OJ@?#mzxNZs0zCNb zKM`;KC!Ec1{ncMEdE?F}ZvWKH@7???%0c&rAdIme1l;%u%BJ$F;N=f3@!`Ke5ddF4 zMSzRHA)bHn7g75?`Ra|I{e{)v{s&LK`qO{;!1DmKYH^gU-=4r{ik30&QIO^)L;AR z&HM9T0~KoT8}RT~Z#n(@^M7|2H?5w0^_MVu`F{8nGTU!{dH*wCvHr~q0QFaIyu9>) z&1m@c;urqxC#SyglQ;j_D?c;!;#BDIdOjPlj4-~E3hEp1LX3Q^NP3e#n1fnAHMnK zYd?-0yb6zg<@0D&-msnk%yZao!L!!)uk*f4>hJ#QfBj$lgO6kU-1q+S-~TPF_n&Wk z;}7unf4DML>F@q&?YtPm-uz;D{@fq=+yCQl>T9B(U!eV;e|quz#qo20_1oX2WG}xs zRgnAkS3mjL-$4fd?_$^agVuuwch~MMtle+jU0A;N;NHT6SC;NAtgp3})|w9<+=tcQ z`{g=czJDF+cI`U9cAeMHeS7~Cyj+?6gmGi{H@^4MKQ?ZBVt4c>|M~^Y(r?`Omir@r zhVG32Z1vC4=xw}>7VwWh{R{lkGbyrm?%!aZkMG~O@w2b~!$11n@89_8fBF3zpZxP5 zy?v*7fBnJQ%EHo}R&!x_WApw(^WMGYLaTXa{m#nT+S)63*1ms(650NjHvs*OwWU{< zUx}ySqkeVLH$V5nzqs+KFHODlr=R-%jottChVeV!zwwEwuk$Se-@jq}f4}?fuiRYv z%FSD!#&o>KjW_=0m*@(CKef?#`x|84e+TpRe(P6$oURb~*FTL}@H)r8_lZ5QvmfHM zA>aDbC%;dTEOb)+-WUD=zx>Wu=)gIh!TDSN9AEss|M;68j(hRN2nNPZjJ;{BW`}akx^pGhxe}iRSV>+fFtne)>6YOsw30)~jJl zZf^hPgFAfMFSRjYlt&TXr+}pNrR|5~uX|d#fA-;zBE(c#%l-aUWI2V!O(s>=y}t8- zq{@2PIvkVa^oN(f`swl{Szp|ldhx;Ci6aR=^W}U0-Df^`@ItMfiDmodr(XDPKUbb7 z>lJHls`A$Mm+tkx^*K!S@s*`?M?f20h{KT();n#0H zSW4x}y3zYQE*NnMd+*o2aEjTMoL6=~@#!a@RN1l~e1qXYbbdmMJ zAGa<01EyZIIPj0Gpm*$^I=9yE-dZ%*R$42|ckkTaym$BB+TFF=&Gmcto6Y+hcW*B* zHCHOA75`aUT3T6NHt_c=EBEO4(jERzf0mb*3|MsDxqI)Gm8F$ejHNrbm+!tZWh_lx z(k1@HVPpls$`D!r%$=}zTnqf z&&PcHKe%sfwbz>a>rdLRwHD8 zzI3tuPW$$LYx`{b;NbSoQfvCba#=OB0xzqJra!R$FBtzML|99@* zy`KNyk3YZh%V&L@jB!1R>;3=a>5VDh|KybM+n<{H5B?q)0Dtrwbc775-#ZD9{itEM zo*TK=zY3?0NOrJ2GZsb|xBrA3qPRb95MA7&C)GJgt-LyB-ic zjQf2jFhch|$2hY>C@6#{ZqJ2vrC~*g?+)W30i@7v=P*7x0#sbJrkIhX%}e6I21vX+ zv?2#SPZ!ne(rkoruje?nL*-gM$4(j`^64{Ep4B**t7?#EZD9~;n8zDN;Pf0A+%|kT za>EE%2%L9g^o>Y}Fg^@>fjgqIPOX7!bFuM=nlx~tIPkDSUprSgv1c6)9IV>VI&sn@ z7;oNig1`?5YbG>aZ|?83cOEy4gYLS4jvK=bje!$F^Bg;#5nhD!bl#Yq8N@~ibv2-U z5IFS!;HIb6ePEJ`dJF1mzYSddE5wFz&S5?kvbG@zdb$G+TY*Z z$2um>)DL`+56833zzO|0=sD)8>kp_+XKgn;G0y@Qx^3QATwI(361-D`%{j6>w+9N@ z@cancbcE^39QzvL1A*A2QHLUa8`?a z5dD$Z@qiT8#D|3%dS!h(_pG{R6%CE!F?C%ZU3r4O#>JF2Hk z+CkH=k&oKVyMQ0PW9sv8(fB+rkau7PfXdJ#i9s6wRbzT;nwT%c+hYn0+i&LjV(4oD7 zpk<3mDK1`X5(|=ooUB2(fbNXc_Bs*Qv&rpt1``8mj`y6vUr2bf%gWT)7sbG6wl7HH zP>e-sDeNe485su+O&>5Ec!N62Gs{Mv1PKrPqe06eWQ7-A?>O*1KMtA9khIlen)L%U z*Z2ImdywlRtVp6Hg&p@GjEs2Epg>@q~#8Mrvy!N?A58p&)b96C6<9j-VDmWu-_ zfFdpc$+9!7bWYsS2y5VxSrmbtlp$Hl`#2U*9boB4zULTUr|}f{1MD+w^GlPZn%O=G z3d+baC{COkpsa~0q8T}A80C#jy%T|)P1-wzco>HlH4#H62w{42jG=G4eUwa+2|o}- zd>500zerCTtm0>x;GFT|Dgk95|8-`3HT}4Dxm@e2avu>)zF6Y;Ls@L9dt8rUL05t* zz;#J>+=GT?I*3wtR4V-^P-k&bq6t7DfyDOj2aYovI5FwkxipbvPAZ~dMUgWcMXc0h zO|Wto#+e%(LmA2tgP{b&#znOjA6H2*+bn(}$*M_e4FHL*^jiV?PG_&V-ZDBn&ArZ( z-L4qZ82@0)cisKw`qQEpo=*mY{ECZ%!Kq`8ET}Fnm@+Tq{EH)AzDi6MW0o6tjwU;> zp8~Q#EL1ZKxV#K#is6OatUn^l=T$(QleB1s;*nsRl9!(4^_)SfHFH}Uh+AiVYK#J zoo;i#i@nrp?{xQ(D$Rzt%ng;ap{Q_)wz1aUUGJ=IwRSMy{fOla3MLr`2D3ni@o+ql zcm!-(9<3Q*eL!!YZ0xUZ?`?IBGhEX$LbJR6clj};jwva2LotV(T^ckt`H7nT)^Qxdu(EqA3vx;c3{B@r2tMn zNbxAf9pPg;VWovX$MQ&{n*2@!J_OCGBV_5sARfmWMr%Bik7E``9hp{fF?8TlsB7GzT$S_0I_6^^2Z`yrt=%u_GL93TwJA$Ae1 zj&&H@#C1kU>bBq|$!OVYU=EwPiab^bhJ@Rnos%Ooqk`l}CPm5v84zH^%W;KI7|70Q zuneTz7b7nP2W-H*NObrkgdIVpLE23bOov`WdU{Oznfl{VbPR1^4Po*P9Q7i`CA(?a z@5Et*-(UcYP9jqj;m48oHPOZ2C+wGe_$PD`*VgSqKzl( zdkF*>tmnqT#-7nT31hP2&##Pc#%}MOt{5ZhV&Jnfr?F#eq>{N>5O90L(Tc&tunOXv zlB`x5*{EsyiMupF$ETjiBeDe$qV&@DB*3dnV*paGb%}LS3JcoZbVq2zMOm!{k`FT#6MOPH zv=%jX?o}uI>U4%?BpsIqUo})hhL-*3bIQ0t*=KtRF*{JH9A@OByO{M;gN(&X^%_P3GnnMJD~v#Qf)$eNQD#{x zR926Y>R|`5Sm5Xw(X4A-(2PHlb1?h@BL?BgL?-8>>KZxH)YRzNIFHK)!=<-W*9~$6 zqMl{nMj{p@IW7oyN@+tm3tiCeX_=a;o)JP6sUc-vn#mzR=QPZY<*C$ zQW%D$X1vfj3MG$k&4h0ohYqYO9p>ry43-r9F+5AygB6p_AFMuZDJzzNfUyA0n;}yM z4#ph~k0HHYx=-Gt9@O(K&|z;IICuu}oDOvjcl$dKm*7zN3 zwVpp1W7FlW2VU+T1~52!7FwKo%~55FhBnb2EvyLJiVSu6muBA@x`PWN_D($i%+olO zt7+wrBzs7F=CL5Y5b%%&owP&P!jA&9-9y*rm7k`IitHfG@WHr)bd9Bd6->zn`G;_Z zYp`Gs&_{+IEnu)AnS!ON{v4x?BK6X9&ea!c`G-3PTU(FlBPbn-81zovzCvQ{o1y`* zI+>+A=QC<(%!E}fD522)6^AN8eT1|ov|w3tl+kT?R4*QxLkB%Bu-HiJ6cUi}^KBXs zj1Sb!rqYBtAr*kfei)g3cYx|cE7qW4gwhMZQ1wRH4~ABGCbj zR;JfSA&3kp8D;F^juO3A`d)lh24c;rbSg2hBshg-z+%gG*tc3`6&ck=PSI;skSwpn z7D@loJy^=@(WuXB^^IX}963ESi_?ZW+Th+dRHT=&wZE$gkYICGn!R&rZwrNaf;p4C zAJbr!9<#9~ng+!?4C87|5u4IJQXZj9VdxPrVaa zk(Q`Is)j%jZUxTNOP>JK4pqc`74}_uDmbk|lNi}OE6w}M-%kNq|+ngmfo>Tk6q-Qy_A`lUgv_VB- zgnpm&(W>i3eUl$0dU+LkfkJiq7|erxLD^@}cS5E)$~XolGz0^wjhnt3KBW4IWHfc+1fB^6#G$E%2XC{OWh#|YS64P-0!1Ye#(D$kSDOxx#G{g|3^vLbo z&S|nF(^hjO3*LfdA6G?wqxy>4&5DsbmvCEZZbs$iFtv?Q49i9}HFz6<1 zIx)cscS0Yd`=WCbWAa}gEKWnNltV&8jYdW< zaPmP>QTZz+8&W7#rBW8O@Ex+$5**k%FnN1Dr)W^XeBiNxCahqo=Cx*mnSZu$fG8Wo zvQOO*PmqBkq;0AkEC}iXNT4XLsIcU1F*BefaGR0NBB_V_Z}7uDJXH_7MGvE64A?c% z*(77eHJ$nLndOpQiQ>$ly~K&!F#et78H`QODI|+W3lgHt1KI>>pB6439qPRkhoe1R z8H?*Co{J2KY!4iJs+FMU&quh{QCbvNsv6=feVG}}W!|S}3=FG}kdzA@2nE1WK^)?S ze`GE5;Ze3hfvj*CN_0MGFmHJ0Cc>Gn-AHP?$La*Pz$va6^j8mN&d42biIxfsI`9Ig z=O1}^4h@fV$Bs0pUIHmxM76ev^;%5n)0fg*;JMd`-9cEcYnQxEc&$|np%lq1&_^4MtOsih50^97Qzh+P3QNup(W!#9*`y$BNsUSlTdU58teIhOohJeL>LFDP z^-}SeNI=*xqM&4xs6m-St0-^~9OM#ztT{ccjcL&BV26s+LL;X~ zrzHgdA7a#`lbD=Ni5PlIL|CLxJ1O|Z79N&<>~TW!fex24pwracJ}4wGi%Dst!ySyB zSw&7PNIg8qAZF%b=J23BDMDKcg?yeeHj05@-4Zx9tOD zi#`&MX0($bWsH3z)HdkY%t6;NWxF8ns0@+MHYyVs_-6+0YIr?#hs)Dmhj`{nvQfJv zunh(rc9zBU_ANz{=rBF?D=a$OfJ4=h&@68Iw(liD!dT$9`++?NuTX&nM4r z%V+AzodT%4@>xaK3;sdX^xY#&{D8SMLR^-m8!Z`97!4jegFc!8Fa%*>7D1>sDuoJl zC{SKW)zg%QR*yGhg-dQeBYSCz2{d`+v%q@Ssnc(EOjZz}$D>Qoq-Gr8<|8PMz(51W z7`n6gjz$YT@MK%o?1)Ad1{m>B>!1d-33*wR3iyr`GZ4+RTa= zu29C>NeYyYCgSi@uzAg_wMfBAE_qwJ7)(G)R)YzEz8p-R>g&PeX}9oc;fgSMU9u$1 z;;SWLF=4SLOqx8mD9nlgpG;RzkLi4LW;`Y%N8esJq(m7~uo;qP3Cp%d*w3N}%<}?k zKCuhnrH!!c96}9vo?EIEyi{wI#v2_zD)k+lJjtz|W zUX+3hqMKXI$DL9jF!x~YDh%dIfI?RMDthi&;ZlX-tp~WvUj{4)B0X|h%cJjOs$JNY z*Hb3XLG%`DTTg~;o z=C}-I4C?)w$(JZoBK~&`)S8}QYVpSv8q;~3nIsFcwZs1qL|&0M;P^?0Qo8> zW9Gb({%7oAElBWj378}sNTQGE0M9=2VyqwR@3(fk$%}Xd=8e+<M;*Ap8+Pn`=97>A&bjdfa?@^L$OIG=0Pd44gcx1ZL$NTVKZw&Z=0 z0}Vz~&4Qb@*t)DNw18jk@75c8?R~v7<%^BhX7gaHTl8vgcfV_Hv^&kUt+B5gEVnd# z4LZys20~2~TpJD?a<&hxfDDcz5tM|mqbpcz@3gz^=2rVVt>oQyd~RTP()tq}V?!=a z@bxBkYV+tQKm)`N(zvfTf#%NR!iO*}!NRZ)FG}9h;M6Q0`dI?orS_1JGQCS4ZpSx- zz1IX}rQj>7)(3f*5)tA{#`AR8xplM;ECK%mzTf zsC4qJlL1^8a7faoNLem(T1yw z@hyijZJV`do5L=7yCL@BGgiZx0EQCNsi27`wCtoYRmW|$oWwF#Gg*1hP#W{hQ|(bD{Z!OxvJMwj%htF!j#UGw6~~HOT_9Ir zETRKh^RMxt`+=(@5#Z>aGn@U?7;c+*So7}_n&Gi!`)44QM=*_uEy1fMMiGpOJBm-; z#Ei^RrbDVMO$kZ?##`b{Exp7k@NI@hcS=NFW0;qij-7o&TEGcI z+dYC+XC}~BFR`>VsMWbBaHrF4g5B6!J9un%cGsV_y2eA!armggFTrdA%YQ+pm5fEc zznDH?lt&Qyo@KZR19fPwW0Kb%$q!a6tdA)lND?^gkOH8KJ+g;0;UmL8!-Wcc>_z7h ze>$W~Gm%&N>V|0Rz?6z^ApC}#R+=ra4Axm z6WF60DjS-s#+En_e>LbLF(_phWm!Sjbpm||st*jM9=i0gQn#=s^O@A`1&m;}OHv=R zb0w_m5EL0msSJ6w8`dj;fh$X(LnUD)i0!Dm6e{7w45q;V@qsM@Y1k1h&nph$hjrvk zTxu>^o^pRszU>g2gHxp&cpyS1D7PX@FqAw*N}6As--khO;Sscl^3B3G<_z=YNtQUx z`&bNY*fKdRZm$|@Hlxa3&cmZem5kJ+Y>_vdH6^<7@CXzze5k^(@>F!Lam#Z+DcIs{ zOBi`ITZDsckp*oS?cKfYb)eTlXYcFQiGx>vqTAvKH(o6jDkhAU6qxkW&kN5i%Q|gx zl24aTf62u3w0RK26z4_k6lQfZ#m1p(Xql80AM3|kq}`4=HmI>w!2IOMUf-3-VhY}S z+TAo?Z$53A@JVey2wxfjro!@P-BIRXRr)pb?XewHf^d$v42Z@v1;eHouV7}y99JB| zU{;{_f$f!2wu`zX2^G*GlWsA`^h*`Z($eWHicFG}0>aczBHJ|XJsjakK@&qBEEofd z6Kerzs(}idhfmv>$Qb36WP_N)_c#wdn%*&vMnuDScmaHT0oFBWgMoFS(6KplAgWbL z3S$xy5HpHv<$5Dmz?04|MIlf0!lNWEP7QV0d2~q2wke3z$J{sRtT~w21`iowd?+3! zA|r)kVL5L@5-Qyn*REtq7!@?Ucqp~Nq^K$-F|GC{#ZC{SR%g$AvaxS=+TUrV29rVI zk`y3|kq$0qI~K}~S8qvhO(>I;g$5=79f+R73|k&z&c3XFg%)w?4=P!0x;SP_0Mn-L7~&O{!&lEU{A$S>?Iqtcv>rffyh>g zT8-*k^<@afTfMV;G8sX86MmVS&F%Kqo903HU}x?M$gb3*i?pE8tY1W^)MvydPxI)ydKnu$+nD=Q}n zw9yfTGm719rXNRmn6?Z@ysolb1tjew2C8lXQJ!97@ad_2dHWhH=2)6jLOv7HojFN5 zb<)BFCtuHtoH4Xv`5pzJ86)865QC9Yhg;H-Ml}PHY6foC>M4q)G;u%9j4&leBRP&c zlF1uUKb;=aycV6CGWTdKlX#0{&0J-yZ6RT~Fp;MsX909B+m&TVAVipOcRcix%;mwt zHfa+C+yoft(z}o$WP&1Papxp-fGv-Oz8A|ro`e>nJ)-*zOR(w`9VgONRY&v_Mn!Q( zTG7z0w(kdr&R|e~@L{n@)Qb>n&Qp=dFWxIAWs_uAKZ7o{-4FwX@J4iPsOFR#EdA88 zB-E%BSiAAW#lfB6QsKl)&%#yF5$BPRESC*Q4Ww#R=0{{IqGDQ1s9GZkpL@~>saU64 zF;gYs;F@07!VMRSeEs?~FmNo7GNq9nv!Hzb`87cqMouj7l$Fof^UJa5sn`c{M=8b% z(_0G6Sys7A=Z6F9m;;j*YSgNtG%@*8UIdv8bD=mpW6R%89xL z5vl3f6E@Dun!K`PviDBy%h-Vl?j$^l$TJtiv=>UE(bQ&aQN(@uff;ucI=zV&CZ!k? ztxVc`o!0u?RS?duO$sQF9})GNN?S~bqeki7E{s#7h2mTR22_UREjgV}c1j~X>uFog z$dNc*DT3w0VzT_KVzpI{RK4CR#4BHLRe+b#X5p71Ovy^CC9hOKvri=#?F1?->P#SVUm5)^XZ5<-GX>- z2HNqUJS=W&$b|{LygdQz9Vr77%~)k9xpi9&;*Qq~E=Dp(UlBs>X^n6dLDq?sJX~BO zA}*3ljW#u|=V^t>Ls-+iOr?0>tc-^Xs)tlcz^H!MDQCkW`Tjnnt`IpZxGR=hz?6 zzKiBe8AGtp^ex9qhNjw6;_W+;ldrFv-+bJ7GEytWq{dWcB3jjK#oQia+BHd;Ywema-3(Yp~1^FZKdFWt@MotR#B;96W@VC{M1!YdZ-`5K6p+laNo`gyYL7@Dq|Fz}(&Inw=H~ zCT_JJH@htW?6&qd@!Dy5T5UQFy?fBzJLsAs6Rx?w)$DYrBTsu$@^Zi%o%KC)ySXQm z=Hhp)IWOtJNpzq*^xYeop+g5nOp8)jh=DGZRFYGq2v(XG;wvUDVBoe8_3qYdQr9Oh zF)z72M+avOW!7M<6%>J?e8C0YmhMIaPG24QTFwwBI`e}QOq>{xoeBE~dJM(M}6U4L=7a3vG(!=B!;PAwiiQo9iqw6YN zSLwP+&#y|DwekF;T`!FJ#@ucNHEb9ivbu~tc5o~h?VUa2U=JW#@MXW%IoRsLhjltv zYCPO-cJTwY$H*1@_0x3?uWNW+!w;&4&%bg-EDKdEHoFAp{0u8#h@-O)X`g@Q4SB&}p(W7X zGj`=3ytE>P^=QntHws(L*s{XtlJ=yrPe<+dG1uNq{PAhion3C$%QWf_Kr59s)XKH= zy+=V$KPi*n$!H{iuR`}2G3kA*L{mlkg?g`eL=`Gv1b%l0Dv`204IZBWmA zo`)JytgiLvVLCR}VzqtrzB2&iud4jTnaNm4Z(rE9DaX1@s7`U)6kAdcL2T-Z4ec6; z(cn~O@vh!mNl?&tRS#1viyxx zP3yjAyJ#?9mV;hG;8F~bRN)3O2&`#E@*EqtwkddWLyp`S;^d0^NVwBC%SWvSsgZCg zN?J%yT$d~~yjg=Zr-2YO<4l{RrIW7zMjg&0J}bhir^f)Q4k?3^X*_pYnEjKG=9R@# zFw~FeX!Qi@OG8NOh5}twJnT8OlRcInF(%Ow$(KHhTaRW%nAbS=NK}=;^Uc7c3vKhb z3=zAwOxvY!a5pq^CTqVm&e$fb!0lJJZd^cs;xkZ!%iD(OxK3EafWp62-zevoc83u%JL09g;k|+74ilmS=M;mvi^N(51K~v(E~T@nQ;8fJ z9eJ)JDzSITA`1{}7i!1D5q0ob!zMdX6ih;>k%bN(`4l0ImkJNW-Rn6GQ-sI5y8unP zvPa4^4Cj-Hy$(+_RK{?E%DN0ZKf@%`3$d%uQU$b`*@Sv&yU@7yDP*t`BWD1LGY}%X zSbf_zjaQ{8>QP9J^6+;lfpzg!dbE1xavGWR#(EKyqXiwuvNg!!S)Ea?1NEIp!784Fqv5GL66V0XMdw0_ zh;li|Z{s=okh;fbFWFKb#V)w!=$fPJp*(&lXM>T{-hRWFy$oxb|Gsov|2dYaZwb7g z1)g zq*(u0Y8=4kg%&W^!2Id(h!e%)lUtO6@3JtS&tMhpx3;J|8oo_{W9GuRj1ayXNDXkBmL0aj_CJmdpnIuNJ=1aH=Pbk z5w3i}f$YE6jMv2gl^C zMy5EtMWNm%hkBdV(NRE2pyk`^(RQtqu3PB?Xr+RPc+|8bCm6a>~g7-5qmpzrDNP?!IXr z>^$AseSK#VLI^4j-rY!1z*UDfps#&CPLX&Rr#vasD;rM651Eu|Z`aK5|b62VDh}SRL9|x?R`SyxGDG zh>PB-N+_Cm&l1iPPT+WK>Z7Tl-PA+3o}rRYJ$3MM7D>(N_Z?b}nWECk14#GT$QF{J4WqtjaHBGC2XxXEKkGxC%%aKp3H)RC z(2ev)58s-x-_{lE1oTuFdg4ef^ps~5N`??`~MafV!9#RcxP_E|oyD)hCe^Nu%=WOMqsf0xDKMkz7cqVZ&eb zg^i8hJj^II8kw5;L(irCV;5)_PDm*9R-$IgWUEq>ts|{UT_zRtxZ(%=( zrDw~|9M1WO+gj7rs{h`L>!@kUo06+s#SAC4LQ>0w$+p+?VdC$p9K^FnFj9b%c|)<9 z$=W9S3zPGur-Lz#Kp1jP(-W|a&8evq$V_szaD)T1HvCcG$0K9t3=bzN2FwCjX*$wj z8dA>1W5=>Z4!_G0soyekrjY6DoKqZamtDyp*5-oy=2R%Y5bww?s!zkWPo}bQBSZmuknf5<2k+%@3nRZp)NhWI6&zVE386F zT8s0{$tijR-jAXu%Rb-j@o0`=Gr(S&j2H(&eTT9rr_QN!HgQfix{OjlQ4o zI)*XQoTga&PSzYc>O}L^WfXrQr(g-7^iGE7bAs?9#Cr@tt{of0^Z#=S(zzJ&mTWu78XTcM5j%P?DU?IK-BlE36$T}q+CHVxdr@Vr71Efy7qXg!y;f#2S_Hndny4AZ zY402noIO$$Ccv%Tu%+x*HFTknT}3+-5~uE7z^Nax>_2cc=IQ5!;0nE zA~_eHaX|=SM_X1dJ^@UbPh2-}Qv3E0@v;r}LO@Vq#YGjmF3@l*q@k(Z&L-uWD zxTMCOIu>21LetkuQfoExmRoK0E8Dq94=2+L!V&~7D}5p9Y}mjYl~h>A5DW+o%bMhX z&B{wuu?X|ISFrpdI-)>s3u2mP9?4u$10^$d3e>2$n~jPnqx}4*yvxT2zYlU;(7W66 z9=1c6Cmhg+)V~B{;RTr1#lW|0edGXeK##wtFKc_gqDnxIP`xJ?Yd#;o^Ril7_MTm+ z3JT?&{+dPWz_l3IOE*tq!{}N(H%ZZaIT1?s_gd<*yUWpd9%VdloOR)uVvSjOn_t~( zCNdMESs1Z-phU&@ipgitg!!l$m6IXLfRsz3UmB5Yw-8Jr2d%?#m8N);V+&)$0>klO zxf$bPjl)pDff}It?(aPJw~hm$Eo7%@x4`1LsaJ zrdYX|5plG$Z+3T|wstz^R(reMMg816c5He_O3XiX0(8|;Y8~7?r24SZPU413KN+Kb z3Of6}`cuO=vEu01#2pW>t?&tIq0%wWzWcNob>X`2)S0Zx~7(=>Un#|0Eun$5wcZrNR>pL>jMno&@~?c-FO~B;skMHcusxbQ-ZXQ!9(`-}LamJ(-%V~o|OUw)_y>QzFuchW#&=XI3qpu^YQgKiC|*h_+LwG%!15D?26 z`1Xk2h$Ei7S)fp2*SXeOHyIm_hd18gFq=ea-a88KYC>uwI3NUm3=5reK8 z9;yo&xF`a(KMpGN`%w=KjGcq6Edr+DGSWaW45o@u;ewpr@vBih7{EL(dKocnbjrq# z;l)EW7jXc41GC_r&qK*jZ?s1c9>B1X=Z&!E+UNYS5Ev|m5&S+rj(KLLX@fj){dY~! zHQc}^K+PBI>;Vv)9EoXLR&p5hD%hAe)*A9)%jGB}713#-KUk<_)@l4$3Iu4nqv6QJ zECqc(2Zfc4$PTCkD=DKNI1c4#uRwLRI7LAWOqC;9pbX`N{tn5Pj{P!2Js_JKRv11y z+;1BoAHfCA8STgIO>=8^cWT#cRPA>oJ}q3~F`cdm${!Q8;6iKH#tWO*F$COxhjhdR71?sL;cm$4oER%z;C* zfTBU~>By}cDLI7ZSa>9aL>BXY!uWA?NKs#`82d3MI!Rs+@n8w8P-f>+JD4SpuZWm< zdgMeeXP-^N4UErQ*big48uJ>{zl=aMKvB||4Yldnq&^A;{#4WBBYGhH=n{naQ)&@BdNmwHLhs-yKbTwEdtl{@SQFCk zzNb&`;iB=_r&Z{{aYp200uk@wz6u^mvigz3?rneMh%izp(e^!OidP9HftyJJRZ|#K zWNpr{r%p?+s=b|pb>zs@Y?}Zx<0V)%^0Q_s&{}#T3W>3SXCrv;ZZJ@SBrOdN%f$&J zTzJI)k?nuHsZG1p!(QJA&|}AYqTFhiPIuiFt*-s#f}BPt+#>@CtVC zl(Z{F0!KBBcV>q~2Kjrxo3xhW&5nn|3sfw%-EL`&+D^AK$2u`u9ZjzZ&k|OK7oePL zk?r14yil%$K<-HL+Elc2j@;!4!SqKnL_&>nJf4ZkPTS5=t4oTBBjkN2bRw#1cXM}v z7I_1oVlIs(!34Q?j-41*h;qhFV_~rP#7I=sey2NeNt58T)^`^2oZ%E4UU)$mmC-P4 zHw1l!B=E5ax5VzbeaATV;~-3c94rO&TjY}Wff}AYVqjSyO6N^xVp_-9-oq0<#aPo5 z5U0#}&?J-NoDbb-5-hAnwjk(}XRAY*fT~tczo!$NIBXii2XSv9ibqg_%0fT`3Esx& z-=Uw=wc&2RV*IOX=xrkil@n=`|yOKllM6J6E5O8r;zp_>WwLz$87C1*S1<4BEjpFoIYiq2^;fbVMkEfq+9+7EzMBGRsaqxE2sJc_vkn> z#RjT9hd#7#kl)Y4bQYKfaW?d9^!k$f3_cF6^9EK8Kf@f)pHYR`2mxYGkby(%B+i3~ z$>^pic_aux!w>|KZ#g!Z7C)IcdY;^mktlw@kG02|3cg-6DDj?+uauFWBuqr>)jQG> zCSs?(yYMKdiY~0~= zdWtmD2%#QaAvum@LnbP~?_HxT%i*gkqFs#^Vq-daN)livli0pC#t+@?tz7Pk4%j znbBLMBjyY=*pZYpbJ0}8mD~QB5e1HO2@KkjH+jGq6&01ExdX!#xfTU!r#1wsbnPlA zCV(aM1dGr@U`f*MD6E)52^tz_$1WQ5U>tJRR)@2;=*wkXbX=$|Vb%#IJVup{YzewB z?k^J3&}h&|7kI{k5Ab2b$%K=G3$bQCB&Q`&O}PdJYGXirn4SWo3X=~}ytpbFS_G8& z`g)TT4PGL5=Gm*Hz=l400MJ;D;DIp=FCz`yA*cfD^en+$LBC3RWBd0CMeo_$2Gss7 zJlu1+x+0xhnQ>iO<7e&=TC??(&uI>uIu1NqY_XbCtWdaySl|g`NbI@_rHAJ*BFddg zQxfTaf~JL;^mZOPxWSZZyv_Prcb}k$j#`?KHcq=@g^DX zq~NoIgZ2h|U%K;#{(qsyhwT3ejXV|){#47nz<97%KoeCuhB=>hSdTpZi0T=-q>o<^QY~d?rZ#MeTO;)D};qTw<>hr z+yPp*K&K%uw`N4>Y4Qy4ZxNBvNmTS$bj@P6cf^D2h#@6ORRkurFQ>g*QICL`4&0#|NrZO?bUGlXX>%f5772_;62pP*+r{Y1FDW;yov z7UlK~=CG_=xc7`Qj;ltpsh&@L^jE3Y1{*9S(V}@!MIYn!Dk1-!h@~qb@=RJTX-&{0 zKIf_w{D?h`5*9Np@!ZX=$p-5C#FfZcB#L7=Q-)YQuR=eJ?M+INUfv>1Azsif7`yz; z6L;uKPSNYWeEy8wPGosN1+H9`j;oJ0hYe^Ruyd1`{(R!j^865;Yv~SC??0rCQZ~sD zGl?f2zm2@-F?f znP`sufwtu6FNGZI&~&anIoyq5&hxY>Mq608NrtidArm}w_l6WG7kJblDIw>TKIVs{1UkgV0{5XemIMjm5cWQZwGQC7i^&1f>P|=L= z$S20i+2sE+qrvHHQH=@;krV&}GYpy=?bllSU9-FOn%VA{oBPej+pV4MvlBykdc5D< zHaqR_w2H{dG#FeL=`)>|3BOh~=Oca5BuQL+0Kz|S9E0XqEtCrt9?$nV$X+TGA)C|t zvquu6Y%pzJH7pj4YEy?&$-YTX@G(I4ei!M_4U9bWFG#~eOB&HRDeZZ&-=<)9V7mwtmfY28@!lw)AUwC+VReWkiWFCT z*j(aDL@BcQb|oPY+0oj2rz=|6X+bY!pqGoF(~^arR2+%=At#o#MygL>`APYTg_wy+ zM606+_aM#S2Qq9)SKEYd;m%%h>#RG_jRTAHy6t$bql#~x!+;9W6_P|m`V3l^fYG5G$eS1>#+L7&s5G!*YlC)e zaIeC^MX2C`0{4dTAaXHICAl3$2j(xfOOpb+^xY%c!$~gt2=jF!POTb+tDP5{f%4Qf zl#a@v1k)6^m6pziVJHH~PQq=p=k(nv(j25MsbyvPw5L-I+OzSvV)-aYU`olLaIh{29I9P;n>`>z=e4~J+0~!{{bZw7D__penfFz z-)wJ*(InSlBZ=h>@v>Aml1$0xSmCpPu3(iWN6Hci0j+4N4G*~$V4yjcG-Fs|U=d&< z!}H9$p0AasDl!GmKp=TSil=K3h5B-+_9aQ@Oc5k=6j(!3hFWTcCGkP3^;IFstRlIk zTjUshu`XZfEJ|s5QiDuJ@i|muX$JI?kN5mBOJ}q91#`NaH-z_}yab z%I{N*($;G#rifCCs9+i)qjLJA_7v$HvUTAD)}rk=?VFx?K=DYcC0uP#_KbAoBH#>1 zbl(#~Rq949w_XKQD*tN*9Ni14$pPOZ&y@-1^$yRT8di~pyv$Vcz)-115wT(-b-CU; zI)6#&csHTzEyxM%^2|Ig>yu=4IXTgU&*#jeN-zEl{eZKPWUr`@c@@zIr1rpyz%*)@ zA1CRT#AKJ&ePWKoDnqlyaSEa%Ry6y7Dk4|XYI=c>HY@=Fd#>~xRIFrjum!7{bqZ1- z%{TM|CC__-vmmE#B$F(psw~w49-x;;(DbgO?nbV&vXYm?(S4p}tI87!X~oW1C{4zu zbdD|sf_DU)=iXGYnX(Hdp6!M`wQy2PH2LCehJ`^(w!a7m<E<$qA8>ZW+pj9iDKN*5NTgnP06g}T|CdC9a|h6D!VA=}uZ+>gv1Er~d&%u9}5B18eU)`6G6&Xp|~MQn_g zgVweB1$f+R6QSf7t->4cl1;B)X+Y7MG%O;)C+|#kZw^KOQc`EB)QAcn8y6lniYhPm z-B?9FeDUK*rQ(^JiPotF{llub60nQq0#M7jhGD}AYg zMAHB=o`nJk4tX}*zQJ+71t4J44W!{k^SsVqF>hkuNp!EuWP(Qm&^nvv6c@T9HI0ua z>C!aPO(CyV8&8Q`gqrF@1C@;xxu;c(mvI4QNTl1NgjA_>Sj#;wd;vg}Q*p-lUfsJ} zx1@}3Jh@6zuA05VwO6BPf1!|YBFbP!jvR5w_|WNDF`eEUnTIYO0n!5J3kDS!GPq_E zDkvqpGP_Jdk`kAZJEoFmvfWYC_Nh_koJZ+#=7u~f#W5mkR}t8(!_8}FM+@8^FhYjD z%sZb#498%Wultm1fF>0Qzpd@Eu%smYmrVhg_umuv7>+u;32#t-R&A+)VODO>8CM~F z&~VvtD9tS%&ff?{2s^vjWxRit=QY`ul}bR7(%fk!?Ldm(CVj%$@-EGf)ZsyYk9H92%#s9Hv^B_Y zn4nom{8V7Iw)=%#FYoej}21zUjG<*>45N@-Q@AZR*XY<$W~HMo9@ zc|f`Gk}a=V(x@wP>sG~mk*`P`&Ppvc>q|_jpGqq;=NqbFU!g9m!mBj8N)hYVtCYm0 z44*RZ*mJRcN?DHra#3bYe#**J>Uax!r*`dS0&Ww^`JVDUEKqVlj!^13ct);AiHBnh zZj)Y{3|KXVB8F||Yv(#p z+w0>R4w$s4yhZ)xnkDj8g)!I>=Z5}{?^&dXK1>@ZjwfQmmm^A9$T>@r<9{(Sk?y0r&BvONd>9{!PE*V({xwuL>az#l5Ly$zfhOgOp-Sb-;Yl@7KfPKg zDI^edg0$~0$U~t?VR)*GN_T@WS{PYDM8hpSG<&^F2atE4&SOR5*QpioCqGj#hkq>K zxd2-PPf~sk{D6#rodDAe7G*02Lm#;#p3*Xf0p61HR4LFbJI(IO@`7+BVu~|tuy8(= z{aJ!b|G|X^1DNjtz#8G~Fnu-MRm7waEkQxca;K2Mq==-WR^LlabB_T=eA9&(^k@~Z z_IeRd8lUsQF7C|`^IYKX9Jj@afOo+8Bqv#WhjfDh9)xtPV1SM=p)4fjz;V5Iz_|Wa zQr(~7>Hu2{i5VljDkX&)bY1&VU{TU^-*)P9;o0e$rW!QO0Vf*B@xgml$0`TRG1&qQ zowR4mBd{8A8W=bbz>pk{%+OzWBnJznD`CYsUqHs_@w=3Ci2NczDG+LyQjKUMF!E{N zJ<4Koyr)SCIrCCA6DMbUMHwW5N=N!aHt4ee1x4bXS;RHSs+BD=^hXrx1STS<_lgR~ znFKp3d9UsCDa+HQ_#pU~5*0AxI&bcnn3^RpYq5vbYL%HS=I4RD_0zg}-FM^iU32h5A4p?EfU)yqDBox_l5bMmM zTMb}%V)#Cu_R666UP$NoBGxi5a>1a9c~%BW?>T`_wA`cs%)OBlEX-NfAEEvhYO+Yr z<{RA&EMoBxjY*Idnn|?&)LU9&Qiz(COT>c~)!&QhP>sIKY^8&8c-!ml!lp~(jlZh^ zLrMp($jazcq9qTq1`ZZP+*0Ll^I)77Kv|@8jF=urF0C%9ZE-yNKTVVejyr7+Bh+JDTf@S za_Vx7lr(MiPSgx&9Qb_61(HYss(*({>W$m0Lh0*W|Q+d>O++=G+Y>*;CV#%v%m3@FJm} z^t4!{BnFt8S=}dyCYVg(Le;~0V!#sx<+z{?V@hd>YRPlX=3xm<+jg{bhdK=(8p+dY zVz{fVXr==^Ql9vvZ63?4!4@XmqFEqxnj;bQ6@;OiL7?d>nHzCRomErU4DPkl)P*if zoXAo-v@?FrR)VX~+*R{782B5V4o!lTHx-Yo301jhJe5i~MO)oSNWK6H8C+R@%Atv9 zh9JG6SbUEo;i_vTxp;}#04h7AGZ*m3ywTCV&KnzBt<=}ecJehnI(4_58hb#nEh7ED}Tl~Oj)y5huPm~&ldo4C1!Tk2UK0gJ-`@{A$s=2Jk#Jc*`f5z%+p%_TUp~;#K}cQ9MBD96v&8%4EeO7b`)Kj z^IYw~823-|rbOYoJd2o5KAdq(h%+mE&L=-r&!SXfe3O{7RYoE=3~|q+XqtDEASt;S zl{R}hG;!ecBh4#wZbYMnN0B)ksRukNvTh2;^W&pqK?L(VgP?E*&UyUJNjI<$hCSaL z$kPXu)GiDe0E4*Cnulc zp)PW;CmDiuuLX{a)oj6Xku2B}@%$VvIUG@CD5eXLc*k4!S3UxB5XOSMVkM<#1>uH% zL%ddqAdYCOa=Om)lpIS)v3$svJ@N~i;!@8)PVZk2e9SVrv0=jheRYpSstL1iQQ^W2 zf@X>At(=N1#966{Bh?kUWwH!QARv|jOR08cPbm1MNvoYBAyyc@V~jV9F3q`msi66g z!^CyW5)4ZT=3C=-$_GiakQHSnB7J8gaFTS3`>i*&yX1M3&c(@yrB>y|kJr(9rd={l z7s*$Z6ftBSo9a#-J) zBcsk66i~4>A_}*nt*55~XEd-bWHV<;(r7QDA)P0@+k^L__<=hxJq{ zQQ7T_ImEicw=$vdy=r8!u2T9|u0;A)#!6q2fUOh?*vjPutV~P_3aKR~D;Y6Cjm;4y z4R%~&Fqeo=2(8nFN1}!(C@`pS#$9-X7qN8q+N(TuBm@dIXhVUvc6QeeHt~iOBf+9s zMie5W9ORXdc)(R3pRydey66Pd3B{Bu7#6=f%6r`IqjIU z151h0bP8fuc+%1F>KGqfcB9Ej5?9X_JZfV z@dy%Kr4duZ#iO|_4g;x`6E=nRwqV}p8+S7E{-uzdaFjMy^tMRN^9}MqhRVT=24`46 zK%IVXzoy?;RsfmUMfeJpl<<0rG9S{#(baE_Z;J0aSaQ!h9p9BH9$?A0tb@@Vt)NWt zVrwVG1oWC?4O0dNHRof4|x&{;NoSd>N~_JiI;wiD_k^44Ji zP?<4T09s}v7J$+nPY8$ma@@9yNgZvc7hI5kDP6vMDo2Tgbi4}4TZg!_C6lb`XnFy1 zO*&)W!tN>p8Ce$tKe0%LaY!yMUAk&BbrtOEXeI3HAa&T+u6j=aqijk9D}@4s#9Uun zH#b@xb8TyP{pnU~M;F^6zUA)HB;6mqJ&Ie+j({E|6i>5M|Cf> z2BFcIML14IkgU&ZS3$Nu=9UHdu|{D$pwQ)fcVre}DODkl_i$Q1C|(sYJw^9CQdGaX zpOFq86R|VvB#C~nY&|@wBb*Ln#;s^5$If*SPTCJiC?;ZR<(c$P3L8I8;;X2oj#e(K zjtmi0g8R83ARKptr!UmH{+Tq@$`xp;VS%Pvsi~<}KH{3HsGfCTN<>!EQw6$br9k(r zTw3?kVXMCGnPj}yhfG$1CnI;{FxtE}C{rV{3|!U%_c`P>wPmm&%CM%5N&%q~snJEg z54<6hTV*Ds#L#8fsj)CGC4XLuzVL6Im$m@6p9oCPpTz_T97{s3tqm>J%~&KtAZs>o z>f)q$S;|`8aS5O^cBRi%Su$15;4%KsbSZ2?u`3>1wO$cI&1loK z(D+5KvJ^!)P`>3Vk<|H38wWgkYz*A;oN zY^lw14%S&vP;(_Nl&0o6nJVWS-?ZDWkyd}a-CSSrJy?6B=4{X*M^1F?1k+ba=cqRn zcU3B}Cf~(rp~Q<S;DN(gX^I;%j-RJZ@CsW99E5T z{@qy`!I#^2m+s+lT(>VxfU)R%CCk|YtXxUD#a~ubjVkrsa|aKRg%PZHZKrQh_85QQ z_9!18%&NBV6D(s~F26av2}&0pE;6 zCY0c?CLlH%9vmAurw;D^(J@QRc-h`t-`(Cb7Vszx-;KcV$94eLMk7gt1x`;%S>T!_LZgP%<$C9I zCEq{gq{jD81sfk+|CBNHzVr?a(ezR&=WSL>hv7_a7;#2M8nEyVgW;?T>?~M^=*o%_ zOd8m9VDKcu%)l6&&u59;(F#3yFTO$)%`HXlPFe3M&x#CnnXk6tmUiJwE6nYCphNK< zR8pp}Zc}#%8RC9+2En(qrZTY?Len{q=KQEm`N~GdwqLvCGknni`g0bug{#%@%%~fYLkMSfljZ? z*t22KTgBt~b{Nrbx9{4#u@hPz9s@(kZWy%lb1qM^%);oLTczlIgA8j~NZ^1@>m_Pm z9n7*ZLT!k~T0<2@jIJg%2pqO>_?9$2T#T2vze9&zURA1y-V9vtghpds>|^K(D9o6Z zWbWL%H}bWqizvFG-z@fC1fT+edp0rYK%6K7z++7~*5zBe?1lN8L%X2{Nl zIv6KuSD_6k=_igG6$?vAp>PECY4JvQYU98b?dQ2l<|)Y;=UO)C3?;63wYXiC`b0=G zC{d$zN_k$wB(EEn${NFKdO2u!+5joz9Z6&X&g zt8_O#-|M?a7$35})$A^-E59hgfHECsLY4I+q!b2WIenb8zNLt9X`J3bSn z1!kh4gRG7?O#^9m_6pzwF@es69OSKK%_D`gkV;a!cnM%FQLXCrf$xv#aI@@p(ITWA z=cKb~LqIO8CbRa1}uq^O__8AaT2vV%ogT4Ko#|c%akGoRy)=Vl!t+HWr(vmVjkcZa`!SB z)Tb_9EFs)oIdYdHgmL9G8zoevv%zx5lItIRj}aRgIb?k-0z7r@Zt>J||$6O;myJ zLp!`jc`t0d#U%Mwg#%5f;UwQGaMJ3u0eNV0NOb;*tE)~4BdW3RQ-X}{L00Hics z(BHIo|Lo)rL7YsHtI5XfJjoYZdqehLetOVB(xebRJC!I%H#CKbKVu8AH3686>M06n z!U!A<1HIj7W118`2g?BdPy@CQq~>dM*-ho&%F3 zw4Rz9!>fj=Of>4)5KPD@xZvp@ro}TWpbHczKc#@+d`ZP19J@n{dW9nDK{f|+L|jP+ z7~KH}lhtZs>)V02qmb}~QHRNTBlR#%OeZm~&{w4+iP@=70N@qwSYXS32bQ1ESI+1J#RHJ60t14I0W+G=8RWU3tldDrCAvOE*x%9tu0c3@DUKatz=9~xe^d5P< z;pJcuhl}`A`fmA_HPD#nQ5gAjPbrBJ=gkrg#C{TVsAD24$5yUiC4oWou8Fri4=yO% zxX&6zwpRR%_ z#LiI%!5sOZKyt%H32}L41BX(XU#>ASP{PD0?;2599)`9NTn;M2bvDZ7!Xqi35=w3O z@m*nkkuDY!+VSNPYU5_Ht7t;lxqSsU$=qx{;6Bn?MN&y9XTsgG&9n>k`AU7_moM4#Ts-gRurl;(fFKlpZ znux`za8|}5kqo+gJRA6-cbRA_fq-floM?-^uwvjwbD{YsY^-on66xx~S_c#Z#Y$4|S8-|^j?H~53*@Po!r%;*{6 zEC*#M_aG%Cj_&5Bxz*lzT7nVU1Jj}ec&kYY{*pbUti@~{fyyuk)_WJpS59ddxxJH% zBCEQ}R-PdzFr^s4pa{Bj{c@F>GMU`>FpU|G^UX-0(+ymAvbhpISCG!Luk0p zWubREshuATJoOy+==jhNiUEXzM-ysQZD#Ym`%{5l4C?- zm7~xt9nhjfO7of_V9A<*T!Bs5-0CKB|6&$q64}fl2^q?@y8^U;bINvvJ973ZvaRGz ziBXPhslZtih)pvkHXpRI`>5lK=D*xv7&C<YN44>#=cyIg74^A_~ET%-{Rwqg8JorRC)ld&t6Qb* zhDD<-E@E6vx=$?Bg!hli#FLpx#<$vnAShv}VHCtYN=Bn@ZK^C$Tg7K3C4)7&nEn6k zz58?9MzTN3UyuF@WKZda+OI@gPBtgYjl74JXottv!;+k2Hn|{O7W?^x9a9$6TnQ*yQin8`_s;BCZDIM9j+h{iqRlW{9O<9-llZp?@H8e zT&w)dHTdP}!+-(kQ9WSY#@j9x&l!fX#5G9EMq@1LQW&i8#8Hm9gWbv2xiHdnv6zGU z_=+aq6YCssaDci1cLb}LXEb}C8M~rA_?+QCX5vX|RrDst_dIo*%2Cf#?s055+xe84 zwLx}5EEc{r7e)y+S8rhI;7g3*FKc9ruW&7idp;5*WS{!QoHS}v+BYieJT!NHR?Q@9 zinO#}{PT|s!=XV9DZ|~pHNMO}g{M`?bH$d}IB(6C=csGZY%)*K5nav>6ytuu} zI8de3xhK(hR;Qrz_}wUGhge;-XC^TGB;%kyex_|3QF?Okcgt&6V@fXu^A(}!aU^;{ zo5sCPgJuWcoUTja=)=LY-f5i*UqGUQE6IWNP;wf<2V@yD?;XCbFu{?i@?CUb=<$@ZAIWs|BC|vfc+O1Karj8?W zyupF@B2?G@JpVqMy@S1e)r4HF6i4%%qcQDqH(I+tJZ|asZ7&Q=xvI9-_!MlZ%?sRD zoG(<&C!p)wLdpdi@&3tV#PB0HK7RE;b+~T?^V+onm0+*;WexscFGzyeTk}IX(8VcR zY!=tG=G#FsV=c9yVzy09H;ZS8Lrf1G=PS90InXQvXf;ly#UWKnD+i;QR<*a*rPa{i z?6}cf7I1dn^?Li5#x`~EGnU%v>;2&C-M@b2cGISm-;~+cztpJ?v&%W1Jj=Q15Bj;s z_l<7hxZvW;b2nuBoAsTUMt4ZVCjLt(t**h}3<-65Sx#pSzS&#gn>J2lO+kjHv*FN~ z!O{?!N<#Sjep$M@V31h)!HsP4(*EKc(;tH`-xq=GIkHV-DMU-w_OAE4Z07 z)wc#k)W%lh%1SL4W#Gj!4yr8@+cMvZ!APc0CQvzzv1{@V--M^fAI|%y;o_cv*g!l4sguvV{@i9A!L7D4V~zzbMZ z*K*_X66dJ+OKz^+M-05M~T0T1yRcpzBXXf2hFI zNK6F;9qQiH=|PVKuF}h{t`oJ=*%&yw1kzT0{%xb5uqiJ$7&d3OJVx+>cqfme-{wiq zSTL89YzPx3;zv^|>JDS)EsR&{II3B>fAe@J8m%U<{ZNfSCn+DEl}ofHJc;1jlG*w6uKd|NHRQ9Fu-D`blT=wjcplp(d*H~vel9>dtCYvS-Fh$hK)) z4Q*#edAO=>8osc>AJFflCwc45F7CKc>3Q)9T0NZgadDpKT8cQTi^p?lVcdkInYh%$ zq0;MC`o{_-e$;JB$-}VGn0-N7;Z;*1yX_>E?FLb0=}|^TuO`@nVJ|w0Ih7%O-+$Bd z?ro}{bVM4y)_Og;0PW@#3-`ftI^!e@%9jYvvcJu#BZ!02@)*1x94ya*$?7)WYARe| z&4&}G8I$lVCDE92H$RJ}1o))Pea zdgajpM!LFpmEc@8Se z3r0J_?VXX1LYoWR@>M)bi8fORDkQdp%Uizn!nuCW8JaT)fg5bs-A~;s&DeSU1z{r1 z#0OOM6kb)Q?3 zcUoM&C}s{gjGlF0>r@jMnvCqBbzCFKYGUGhEC#gm<|I?b7^r(zQ%I2RFo!e+iI@c~h2JRUgio8gdMZ(2O>p+crQF-I z>jTn<0yI#T*>HX#AxjOA@3sNqk!qNDrk$qT(aqBAMYJ;OIkXTW`vm(RPEY$s=WL3& z9o$~s|NV1hXkr;`tnagoF55@qtSwwl=**(L@UW@OeQ#w{HOF8 z!KgA+Gu&$n7E%qnYiYU~wwLRj2Xn~fv4A$Mk*&h6X-mD1)5Wy0zt*Y?_TQG+AXY3% zcGj!-6h6Gp*XIUwf&g-!1Zd_^3e}U~$GJ&1o=<0}j4Ik)09K@X8GINVo$r2wFcXz& zMU%}S(=Eo$tk1!v6Qwy>^X#amT^=T;c?C)HCmfy1uwKfi9W=d~IiSMD&+%Oe3^4(h z{?5R0nQBru8%4oZ@PF!Gv(Ys^ZvAn(5wW{S($76|Kqs$rv^oQNYC2_7%aZx4)Xro- z0llB+z%%p1#$bktjZHL`xZu;^r(F z&u0%$LJ*A}?xI?wK}xnr6eGQmD2+hysXSx>fX_C7Y91dK`2aeOCcR*T<@`3UwLHm*z? zOVe^Fldxfr2-*j)_FxA9%gVjQ9H?F;an~eXB)=x3G07Vzl8tSuTZWw2vI}KM^;G5v z0%+Q{qJ(Wp1Vk{VY%<=VP5zO&df!t=*7De{!|joaYbAYSN6e%iR3=L8qrstE7Aky6 zZK+n37>lqn+SweNpubzyT$mF?w;&<68ilL(eRFM^!gejG3Ao7Ts0z`Ml&lnfU~yH_ zEL$<_CtA8|@>g0%RlEs5>*tu}a;5NKqwC3*HR-YG#+j&2`CfxY?TKW(NLH0EAqQk$ z>x^hcm38EuwPdF?6D`)AU-Jb%$CIrdACi=kADC$%`m`7I(h(_x%1Bz|ay zFC<(#gP)KxatEE7IOo!=twJ;hsV zq-p`xTD_o}b(c0@^Z8&lUbW6`U#!8>{Im}>JHob8bWLl4oskabmk9RdD`+I0O_mg# za+o0D$GI(5fO6NWp-H;5g4BqlSeu+pyNup6xy;u&qAa9aR_Nms%C#Y^L(WK4^(V7U zvQ+4@DV#@|zT$Ia#@16r*6dh_&+9w5K!>wT@2iRJ(fQ$|I4#;FE}JLsW)~MlEa-uV zjA8mlY`HZ=3n*(I<>C%*M)NBi}bxXZBL6J0~@m(=m=lnx%laws8lC^O7;I zt%CotHN(7y_CQLM5Ij$yGBXi|l~7TN3H_RcM%j!5rkiGQoH@^f7Hj3{b@HiJ*IYOF zv3GhjIC=xK2VQWALG#CKjd0p86QHlrLZTjTNHx2XHesJOPo0!zPf+5HQW;?y#`O4hJ3E8l&?w9UBBA&;#ZSD^pXet6nH zJN|IG-xu5f86s09>IoA@hp}O(pAKKCWoM`bNfU|ATbs|n8VA)WiRJ<@smx}f?vo*j={L}h!qQ4=@bhNz z3mO2`4*9Yzo}!$Ou03gvhip4gc0}{~fBNTVy~FV2bZ~q+IR8i3dqW#d_^Nkw zup6G8f7pL(j0-IamMMebe$f}hDD~N7&}M$n#q!6D^lYb%jps4~jV+X3S8LML7P2{} z#j~(>jMj^{6SKQe0xKv9`&m`mLM|`uwlLY)mcC8GT;yJDH`QoFT=a4(A#+Id#r@1Q z`WF$!ERMve&}<`t!~6}R%dF05vry8LNDwiLpU;BgHktu|mA0dG*3NR0Ck{pcG^w)$ zurs?*!3_uP$Cm(B5?&>@QOTU-VbQbNdnD*gqGXD$!OG`yXn6VeJimmsCqIy|LMi9t z*f?wZJc_S*Zn9(?D}F^Y*P~JXgPd&*&h*fB#Pe+wK{2+NSyRINc}Be%iCu4f5x+h@ z?Y}ua{%~~AG#1JYVrs%AgI6R~cb;`d#pNV9Qa1}sMuD8RC6LHS+m9^p2Jz2Pf#8m<7ea~}WB1qX_5nf`2fz-b-KOgqP1UVrotnZ$c)dz4ui&y4&C}5p!>L5W zWI{q#oe%>QHcg(V?1z^k*;9YIhKU3cUBKYU)_PS}Z@Pnn?~%9wPe8E030p`g4cXt+ z3d@|Yi5+5*p)4_|HRlS3Oj;1gX{|!NSY4~K7-=hBMj0-0BHb(yOf&O^&jwiUOZbB! zG&T+i_^(=Jkn@+tpaX=lN^#HBlRl@rzAK#X8t(p|sEI~0HvjO`PL~`rlaOY)K zNOUzbBOVaU^nfyIB>jg)GI8F~8Ww3ZE3UFKRP`%-arrj`A{F0!ZTdzKb{CE}=Jaal zm>9ZH-_IwLZKHdxtD59+wonVch6qLW^@l~0+p}8b7}#8bTmCfx2`htFzO1G~#EB<# zBOKmLMfgbA)yp_uy|hHwI-K^2hJ3YlcilA}`}(sfAMJy1J8&aJFZCTt<7V@71ARJ+ z2}bk(UJRQX;|0{|J3My7y6Lzq=U|!(!;EI)As?Ejj3iFOSU(;MhrEt&!Wky? zw79gG=In>EI3b6Z>}65RbK(q>n5Wt!;pc|8CG#*b2lm22aI6K~d8y>tl?H$_6RMXS0I!#85+Poyi z*;zO^+dn=!>hGWT4~!|M7f!H}+KUw0OimuyRCQU3i%H3Y0^rIeX+{^xB*c(Bln|p~ zA0J4w zy|?}FnGNYO!u$>AN!FN<&A0Q*V#&wF zj@)Q9(bf_xjPK*z^;mNrU7VGEoyD}G#z{e^?o_V9=IP8|C6wyt>A}(2DaR)v(fJoJ zeU8CQ$NettJRJRpiRJT@H+Q{*`_pFeC+tbr@qMv_i16@eGc1qxo#c)rx#$*F$a$#u z!r_d5!<;aTLgWk6*`rD8jlh&W0(CcdOny2kgTlSd41us!0Sii?vfG>qvjQ<;by0rZ z_!Vx#FsG{$iP)nExE{@98opNu(X!$;@r1Ftjb_+xcA@zCm@q`}HDAnSf&ppG+rpaR zsl?}6PIrFV+ke|XWw26Q#i`Cj1Vo2H!qJzmXnT+G6}{~Z$i@N{y(gb!*)^T{cDQ>4 z`aWd=na=v*e4dQWo23-|(}_sg+kO~#D50Y}W7xTh3g2~EeAZ$ysl$;VkuFc-o4D=` zaQ^NGJ^MY4%v$+-)iP~T(fH^`_qOJ!5PWBRa9^%fHQ9Kc+OXcqN$}yr;NZywXmr|_#26C!*&KPdR?Q8VRhh^_+XBigK;HI}ecim?HF-1{ z%_mW53~0D;qL3o#(g(`XhUx(s_IYAVxEp zu(a0JO4IL#ihdpjzD9Ga)Yl?$zwL?_BhYekV;WgBPVvW&t2d5|nuOszaX)5 z@mke3hJivzozv6fso z{6m=zlR_~_S=g|i$&1{o>ZPmI{;qM;G&t_IaC%qyEnDd3PcMVbJNb8K`H!H@c55VD z|K#(@hSB?Xm3zoQH|e!yw_esio?NEAE*_hjcLNdJO0s<_)b;HI5$ovcQ1p(!P#N&eE)konX}!HgLAxy*+!IP8rCMXHKYz?Se%~m zOOy#>GP*p`9WQ{1Bm zDeO-G1o_0`X?}Kf((?Ji^xk%@UtfZgabyHKBS_>)+WX9pi2(q!NMK^@`BU&+eizJS zWQP3Lc2L&dynMKtN0}Y)x!%*)hW$G`n@!2I&K@Sb&-xj3S)NUdaP@Gus(ABo`s9Mw z{){zBG`X9I`@dcWd+YRFROczlQ zYpz&MgKKayH*;n=@QzAw5@u}c%%pq-)DmHTbA7@NjVF?iFK_{66t|CWqHI?o@MpW4 z*5B~FZERH1qT*k}Ike2+D*Tufp^?)!ITC!DrHD`(iu|oIF}*K{x2!o~zI(IJ5!X}6 z3}=brr4M7swtalRF`3vq189@*k=P!fU|H=TrYq_!$M!HmlV-k%ZdE7GYKl6QPzd;n z`A4Yt*P_;_=C9{mOVM9RF^(-pho^>-PUIKsB(L5!JlK0lT3$3GN)IXOH%=vrv-%cE>SXLM1NYwPX zBoV>n*evWdp?3$VVIQDllw_dy^=i9;)PaXVTD?bYj^uTQLiSF={*Z67{SZ zNJ@XTg^>UoVr~*$))NJGDE$CQl6ag@JqkK9jM;O2G>Rt-7ELW;5Y2foP15GXR6+@q zQ|+Ur={%w)0o(dXbY648(@rzI6^tEiEzaH;i8G+@opbUeh03-tF*tFqll3wW6bopf z1W;$gJ=AeR99xX)8d8ohrzT#1e^3-Tc>Cn#arz^J6;5m^3=624HMFE9YcMitPb}?) zGu#_#Abz{sX82P5c?+`q+vH}Gl|=0cwRgA0JJOg+O4-$pKS9`!edZ$vS<0BUJ1^Zl zr2TnXT*WZ5fv_r<)q2%{hi6#qdyhy{{R**8Ubm2krcb>Ek0kHfP|}#1VZTjlqh9^k?P6}33E3;pWE$BKCcd+dj-{ zpQtl=IUv{fx>Xu~zSXIuLcIUd`CruqcUvn7(`g>o8Z159{RBTdnzvXsf06>z^M*| zbX$horb}^9j<79?|4x#s@pIwY8EiiPn(FiX1){zM_`7TWSVm`!EG}-nce?9zrWdzan5 ziV%r_j@+~tWDHh3I6gUfUEP7?W1*f+-s~1mf-9LKxM7PLaev+REGOLlbGO~tp!p)h zalbgP8!+B!ZDSAIRPwrj!&Ag#zf+HryLjwPtE)=K_+56Uqo8gVg%Kd^7I;VtjYOys z>$R?{^SuYdZ$(In?)R^f$@s`OyTX6Ne<3i7^khf6savVRlDufR@hr2Gwj>eKFc4Qm z*qz0yL^;_XNOaC&o{X6_`Ap2)(2sB8Jcny(Tas)ux0RzLit(#>U>&F@ZU*sW@FzxP z|GwCH`B%N|h{{?+7E}Lq=jHR2sf`7@Ys%i$N2{h8<0{c$D*ca5Omk{%Hl#oSjiA$0?hn^7OV4w}qH1I3CT5gxM%G`#RTYup!mW zWD)PvZX#=IR)__vAI@}u!YUFD8rk z6`3_s!2&Tg%_?URnEC&yP72$9+Or>wNCF5WIc6oszF}!XL?o58>|~u8H^BVfXpEO+ zwI}Sh%$%*j!~#|p(8HY9Y2w@h)Dg!a(EXgfsYNi3 zh-JLW!`%L5`&1_K`s5vn%Es}bwxNx(9I5~rvCGUv5v0uiaGABMB1`YAcOv`sA3kfT zWTG3>8WZQP%%h5qN@qr+mZ>r)DvGV@LR|P>Uyo)M&{;n&CDbXDc&xu`do$}H?Z}Dj zyjB5d0;x-SG&YZt!e8+ZrLQeSc;(N3ksuBpDBK6`}F|No(oG53b;3ED* zDT6l3O4w9kUToFtRc`|W*3kBoq%4L%e{lz~_S`Cb$1#Z>6aMsV{RHx3mh)}dY&kKz zNn}&1FyApO7HB{$_`DdzncA+(;5fJ}_LM`-Sq@<6rx-<}YxbrCkj;FAYY5_!6;|L3DhdQ=T1H#K zBTeFt`dc{Oa~46mcrf3he!!J{!7AbOCXb-$Oh;BM690AM_0xu)(13 zQ0&);-H-BQ2E`7$|JkA#i)T?y$gh3d9cdR|wZOPc;LExdeF+a7dV(zwbfCNe!evc} z>V}A~ip4Q2_MC{Y`1yi{rMPlj7i(OrWZ^YjbLx6*Z)F-rwO3W}z-5~#oE*~5Huh_J zM2`jZ4dZym0bDBAUYcGU$EMNUfhOA4#a>htSvh#&1%~yDxTI*W;P`({S($^*h>VdOy3CtD&p0`0sd0a*%{rb;F^6 zplmPruLVLz|FUTVi%UWVt48`BHk=vXSQ<1Y-1y z6MH=gy&}ff61iW@I~LNwMVYa@Lg>1^58x*uq-+46FMA(GeA`*pwnfPxRg2cS1 z64PWf4wG3c)ac0cQ(ry;bkD%q{7%fZIC!ItaG|&kG$LLOl`KM0N$2P zO=&Hw6^Inv&GyMQt(UX_J_2fK4ev6WZlkp!_l*L14I3h3(Z*S)*f+5uqS}Y#^#X7B_nxL|J{4>{3|; zeswNC($d<&f8&n%57vVPZ5!;tFJMx#7T6t>wsytrgC|~8Spvb}gxXm`&sFLiOVw2c z{*Hc18-AECC2xGfAn)$KEVjgcnj`r6@n+YmYs&RI&BR)b z7*;mFyz)jsLyvN00y(vwn|aSL5oR%D4Ylavvhl9F><_#7Pb2jvNUUk74wi_XW&<(m z=~@lYg*0;1R}x1Z7tr0Hbs|qJ=0yPnM$yINcu-z3crE4JhT+#ND+)jtbZWG9!Z#5A z8(&rL(ccBkoA;>3dBT94sssYUMp|I{r=`lPR>@&NCV65*Ny^h+!&PqEc_0^b28q8!Z7xZr!Ex9T761wP1`v5%qXmVUK>^uo=nyt{Z=*bJy|S`V>qAi;BdQGB71H_)4tx7+ua#uxC3T#MHYk6X@>(}I zc0=VJb5|7|{1ebWICX5acD#S^7Jt)dnSiaD_RGJYP^*(K5pdDS7$P1t&?V(l@>Gz22egxFV8J=df{c5BmwMwL1sj zczj+u9Z+AvNWLk*U)LW`-&>X_KNhPx&O%$F&Pz8K42qToG=st>&$atKw~A-AD-jOq{h!+#JE4Ff}T448IOO2QA!8R*CeFUwh;Ke1X7^ z)OQ?XT8^yKWQ_a4?83nwup#3=zc%b&)h04cB3FGVAClsFqh-??>%RNA^gtBGYmiv4 zQjQIFf_HW6ebWd6Zo90bv5GWw<))THw^ z9H5u&I->5^JSrHz|)SpqqaQPe-^XW9o>EsI}U?@-N)L77VEh3$$lqF$&8RCX?&6MmR zy&@%_Fx4wxFJigd_TgT{i`En1ee|i`c}x(ihe}3rT92< zk%)_vL;4oyVnJs`Qf0bNNDSl3b<;9`tt9?vQp-MoD|cMyZpj%>HfggV)Ym_<;V{&k zi;qc5^QpMQc;;SyH?UXgHtVIsp5lv8{$PqdfVSCVHx1}R8ZU5pcGKSWSX9HjeJpGT ztFvVJZInZ^-XH+8fdgmbPTvZ=H{5H63Rv(u`3J`*d}e)3Z9Str*3A6rMPDRw@7&x z4h5G#jL=2l5@CX8I|8u^I&j85DSXkgP?Lwrn%Pe@uW!l>)3Lo(1z(vts)9KJ2;Qn# zHg~8azWp4Zf?Om>d&6P`ZyHJj62SXz;LL-}DG@@m#i7K}PtF65Td5vUAxJo!R9-!B zatd1m3s$1(Haoj7ik;ES2WGJ=$H2@OBLq*=VAEt5{K+cK>~A8it~#4%akBPUcg;#WOHoSYcPcz`W?^n*yzaEXk z)n%;ip~cjV-IK}{{A2pYFGXw`6*6m8bt(xPYa%HgTbIVkk5cPbf_xi)fe=wM#W8O? zEtDg`eBV(BI;K?QL+u;hhLm^-1Bo{PXZIob*Sz*llY=sB?c_3Cs%Np6tcN| z>?*>kr#)yEN~w^=HaG6*5A}rglX5%G5=!ADzKljoxxIXKO+Xe1&5vln63Rw4Q3uRF zPH<6d{DbnLt%5sHxf7^Ky6xGo)b0)!uSawd@nI z8&*8Dt$nEd)ETwZ@h-SZ!fB?uoNO2su_&i9c4XpHcg4EYFA_eEuoVxHt+l(m`{D)v z!P-Ukt?U2LKRSOmIC|TvW`J5K6bBc-YUVp!{bnP*hn&KYAO3v&&OOqMy^3iVTdzL6 zkzlR{jr3>6nvKK}gY_??-{uLeA>v0EXK+&hjL1Z#K9#6zD^$=rsy)e@)*tjPl z@MW5^&Pe>o*xN*nxrea@#xip#nNG7CqgD5epF7SCes{(+S&N{hbpEXs`l_iyScBKo z0`8Sy2N3N!EFM@uSi0wH=jR=kt>KH74Z9$A{pM!;BBH4bf)aWY zTPrF!I0`?U^@)P#S43@khIxv?;~wD9Y+Waxp2QH=J zz6-wmo2}-v=ZqbZp-uW z79ww}IeF$6_7|*J_$d^aLtgCgBX&Rvj%c1-UeUSTtA=Ef4arcT5v3(||8O>wlK);K zxsLBc$qis5;)_5ZpTNfmzKHDcW`6C!sA|d9%`8N34qAVGp^i(|xDeMs26w! zafSHjP6mD~&nDAmq2VcvYfOLuT`*Ltt!=J^?Mr*j#B)KDowI*0YjA*wg8kdouv4$6 zoLO|nNUZ{vLLq%28Y3JjH46@DjBjVZn&r6r&42&>`LDmbVcF{qdV^2ja-ErIXl~46 zH%Po@b_9UNYa^%E*&}%uCJ*PVX9=~-DszD2G3Y@J>vPMtu3H@}A)ymp!TOd@K9`#2 z9&C|>$y`h8pIv8@Xb4BoqSm!a;!NT2xn~)ca8Ge~vbdmWAb|LCp~KkelW3lfuEvWQ zme*aj|ForV(WGRCpvbfZT+m$g>Yzzz z^wb{sGN%N#P})`RGn#LMAA0*CiMgkP{#kg~`>7M0!E4fpbdc_2fqOAEXNcE=u0w#8;kF20_xa;D z?Z5NG{-?98PlK(WpYQ*IH=`sUQA=biz&^eA>+kZwUG?eH?>4@??r`w*1hfPttbNkX zMS@SCe*GP%IFjWj@u#izO5*l}e0<>$DExl!*XH+B!p-l~Sus+IqboYr@AZCNc=zek z7O|F5Htj^S*(C0KINArUk`J@nyTs_YBtWLoxn6YUiC$JNOR%4%7n5XEs!#dSbZ7K% z#?I-L$$}_1DLRqoJforPE=drVI0N!2P}W-Sbia4d4^R7Vyh6wD8V3YbC(1`8cIzIl+V!v60Ft2dd=7Xxx36fvQH#V%`cta$Aw27!oehqU zPL5B{TeuNdNE?G%GLuVkFxP41ixW02(VE*!YI~ip7xTdny{@0BoMaGMxtE4zh_Fy3 z1N)t(Z>hoa$vFLz0fxp3jDuZ04JOGjk0hFyk{#i=?Av})chD9b)y4~u-Yq$W^Eq6y z@oQ`usdpt_#Fqx z4j0~=4KoC}&~#MDW5KBxJ}EX5e?vV?*GCTHgH?3^yqfT)oTSytLe+Scko-g4Y=L-4 zGRe}*FKQL~7oAh0DMPxT98ly!jbMxyd_3l(GisvwPy1)bA5QoCt^ettpY;x%RrwSb zg@~EN0nn0hQL7%Sctx&&rH|9r;}#NDSA&DXEk%A6CSzKQ?RNMo%O+dF?pA9Qg#|H< zpMPnMBkC?%s#NMuWa1m`uu`wEC(Qkx7q|%^WF1#RPJ?0cQ7N=9grnJ9#t`cjs#%sM zLq<$uGqR9)Ei=Wg7*&1oMR3WuL9gKA2q%Uzk^AJTH6LddAAIVZo>lr;?}MUcAZZtYXCd!|c)7dkwUWfN+V|@s; z7J*}w7yBG=tf2A*Jqd7hch!%g_hw^E15zi+`JZ~8fcF1d~?$*P`#uF5JVwh*%AQ+@CqiKwM6i~>s5bH+(t9p z@E4M!;1_bV*=W7$9kkvZ|Jd3$TVyt5Ja;NJD`?57_Y;ujSp&1j>L>G+CJo-qyf-}3 zdwd=Ij6{*0Bztx{E?d#UEJ0@tHxtWjzYP z*tP)m1i@C63yi2H5yAP|3v%LhoXS;3WO_hvzYU=@&M)sn+9)rG(2gvJEOk&x08pgq zA?I`VRsfZVMWrQ9ZVIs(kK0?pbYAe70Uz_5uWdmlD;3j7OK=w-K@pHV4$Nm5Uqv@G zJFHBkdrZ9{Bur74Bqa;KBnJ(XF%=0lp23bI9&wZ8S<03kO6;Kj>cg9_-KQKyxm4yu^!~f!{kQV-`{T27_bWU(9sD4VC#T2zbkIIN)yK2`x%(9!^$zcz|I^<$rP66XJp1s9>Uexa z;xS)csp_27gGH;f`ehq?Ra3B}UEV^m>0d|L>i~vDC@!x;6|1MoWf=ebOAzHTwo9(6 zoz3(yDCR>Gn_w);TYzEV1Phml1;8t((l7xqsOhqQPHDqUXjttLSS(o}<3KjlTAA#E z-@u4;GttDdz^{ynW1w5eDg)cgOZEzuIy2};i`Xh1-84pn4W{Z{$Z;09e!NR^M}-G}pA$GZd2{VLV=X%n0%T4hh*w&= zJF{_9iE?LZr=i9a=1f9az%*@7+sULleq6*LmI;H%8!9|lW*X`tsIhdOqDFh~m`qg% zZ*Bw`whtM&u|nLaere*Ba#3UJ5ETqrIER}~Ws-Y+#^gBat>b^D^UPZG+hKbWJsbN| zWmz`OF|#=w6KJ4c(Hq!WPNVC1hi|2fSU7_T#Ws&pV-9zPwV0)%&&D-&P6OgYuKO31 z33hL5P~b9D_|ogayFRNOk)jRTBA#5(2FWKn6A8INU$3Th0&#FR3L`low7z}u zV)rTkx9rUmc0t+zZZfA5T-YMehHQTLeoGD-S zF3Sj7l>l~H&zErCX;weA$y1| z6f%o)oSCaSa|UntZxaPz)A6ch*%6vT4w^hIU|B+2R{}eM%i!&P(Uc#P<32RHNx0u# zviHxNjaCZq)6#q1@JDHL-r4+U#zcNHTp})+W<~QpEJY(h$ac^3nX0%9UzAa2HHT#x zZ%M>DKKs6R+CRV*AMxR5S)gkOYZScBxMHG1aO5{vxU{?f2OE&lIsNiK=4tX9?$V4w zOz|JwEcugD$gh$yMK|aFQT=bj+X*0X*T?ZADeBRajh7(8+{DcM3=xktfO3Gjpu`j{a}48VUo<}G)9&7t(}>R+ARLec)r+d*j?w(PU4lDm8TEU zg3oI-yC`r;iMzGd!kf^_Uq(r+vZCAi7xJi-v6PO8zvIqg`60KVxMF3@FgBW7uP+v} z7}<4MZ9);{G#T5)2KvdMwodL1&<`EVNm%h^!AH^4gN--~IO4{sJj)G0oiVnc7MYJL z%X61!t9s9L#p61V`+Rlji5vdK2KejcflfoBM~{FSvp|K$Udp|b*Jt5r|1}QyusnQy ze7fIfop9r4`TI2qwx?(3v`#J=;d*IJyUw`vgT*@*lzP~`xKYg!h1CdP1iz|@LZH+j*)SY_NH2P z5HWH{XIz|ADgB>=i+MV70PV0NB>sjy4JvOg1uKWI%w;7E;|u6ybD7y62Ap~V17)%RjtMM?ISc#LRY zS(uo{re@joe5M*I2BK(gy=4ok0qX>l(ldJF_BHpxhMQLFG?9(#RyI+aB_CN?!*J8X zXaZLScn@ukx4P8Zmm(Z$c{JCk)#C(5mI-XchxGG#pxL@=!~NMy;Ga!}@JPWl?=qi- zQCa53V9C7m9`!RWC#ghrA?Te9iq?cTP29@!eL&Yl^kK`0sg`Tol`-jTKBF1;N{t3X zQ{G;0!2kUG&DWz}+-uM+!oBK?aPR$K@cz^Pr(b^h^sVdRX?aH-d^o3bu&+)OQwFGB zl;3w*3iu8epWob>pp)vCAb&lRh|JHwzSF;6R=S@GqRux(iboN&tJWDe2a>|P?$hwh z39VDEQO?Cf8fqXf_c*4S(L8{bIsAnDFdu`~x7fzu7PW>~brPYpbeJtHZW> z6-!(taq=UkV18<`@@VRNsO^Oe$H6i=3J@an?nqa(aUZ-BO>U$6LU(%m**zAuRrw65_>7hou^bqo)=ES4$!1y2!8yU;k zOh-isOp30S_LKpzizL6LHFDsN4G6lJWb5bNhFq}b z=8Ib4bMF376osgTDTpT}E~K(?k?Kt!ReL$hF&S7ZYpuWku|k^4{Z9DT%i6MDlB|L0d3nzz z&zdWEBt;lAjkNmc!@J3w1&$oFX#wq@e883FQ`URcWq=vb=WGG@qj*0*zHa}!UHLhx zW@g6YHkt=AFVD!#`4XleB@Y}=Z~KcRP!+U3R$SgUai#BPWir7^!8+w1_S&=bE*`)~z87-JfGz8|bns;xl+9%tFb z#UG^NG=uC~Qf<<@L@-MxPa;v#EMs-1s0=bcbwMP~$Q_?Nd02*?PuDFqBKE{RV_Sut ze>y?@ubhFkXI4}`Witu1XK+j`4Odlcmdmg;=C=cbOF2k4?6OU?U^W&nk^*hC}Uk6Om>lS5}^9Qb`*S3sq7T+v};W#JGwpWw4UiG znm0x3+31R9U%L3AW{GBO$j#Qp_si1FbMEE^3ePqxZnpF()K6j(bjt_|Fub^Xd|^v! z?UngC>MuR`WQxlxStWcq$%fHHhwG2m+b8$g>)u4%n_-ovRQ$v+%`thu<1IO`m+d9=NwtEMe$}CBCj@E8el_;Oy}Dj3LUO@4ooz>%V;SU*G;U8jh%* z?z#7B|DgZ6_57}7+`sug!;To+h|gfA4Rr$wt=Se@L}?fxo8KX_!InJ{=xug7WkKIE zCV6sZsQ?9Kfnw|7j{xt^Ky(UiF!puB&H(87|6@Zr?_;IIO`0DhfSZ2 zxPZz#?UmOVOS*vj$O7~vc_H$0i=#nnc>;SJ*TTi~ajufiT&7_Mm3wX4#g?WPst!uZ zRB)Ev#yL8tl3FhxSv&V|Y7G)FzE7hmoP7MmiaH`jnAJ{XAC^i70)BCBWr}b%iBk8D zttA)USiq24a_fv)dF_^Fna#4xJepnI``R^0Mf1~;nZrOFzLJY?Lac6AnVdIDFQI)? zNmyZWc}5%X%w33L1UF@l*XvZt*I0RfYoUoD4kod5_1eNWb7? zf{@tSG_|~NA@}@5!GGFuS1aV|WB^iaNt-XpY^HN`8PaaTM-u~*KDI!|@HP3O5fVeI zA`~=)Gw;nHh?pIg_kwv<}*&o_V+?3(Iva1zZ#sKrOj zYpk8Xh2}=NU#OsA&)hU3=67uw2?v=`-%ZN<*0IR(RW>5rLz4tBs`j(W_KyEAXurtv zRWvwlfd3^e6SF=gH`z7S*xhx~a=3{n;?13ru*LfS6A44C=~lY~p(wDmhy;;FDeb)UpyFQ!%ZAmaZ`${? z^SyS;0GKX4dp!vE-}TM_05>=~?;rKxaO&P3^iF>q9EGpmc<*{AC*e`=q>}fj_ojak zzCPaXy<2?Wkn-sGsGj)4`QY8){2zYd;vBR<);J9|$ZIs08V+otK7cjeS=rMET^tnw1TTs-@F9okYpBe%>@qB(WEs zZ7mmej9tkRcFv~rlD0NbgiXAn0ZYmv@O1L(_{o@UA%n2A2<(R<(o6yRBU+tVg1z*%k0N za2&dshSPY;+BK|+St}~15{mlO`M`r^D0$|fJ~_PDrUG2nvaco2PH~mph6*rLw06>r zM!U=e!l(s@=WG&dRBm)NB`@`nxjg@zMkDp~ljoDe-bu*3f!L2>1x67swGdg#f9K4- z9crIRXU_Ub>G16e^E?)}J4Ec0JkTEbx%s!RIN=w!S$_SSrZZPng>BE3)QL3zXDB;K0DY`1qr(nvG1iKyYa>bKvqDs*L0P;?bvizOl+}r_naAhR}{t zjbN1|EcM3C8Bw0`28Zf`}WaX{A8og2ehpScLN8`0Oo>$tk1U;nyp>4$WjXq)}P( zTPwU|xTU8nV{X`6O#OGoCp5mIIP25W`u_N|@4i%HLI9sM#5dw?e7pw1B%RCN>C{Dz zJLzEQ1vOlLBjOK$G`%kvJ+zn)bK_5^%(11u{c!c?X+=!Q-feJaG$feK^GjZS29$qU zLhqi0lkkEb-%p@R;R6TbnHj(p;Os6fQZRLve#dfY{Kivob&C{=dyPai#TW^AWs;jX z6imt$sgjfxG76~uP_hTf(L96d^x=fq23QO*6^;m6b{_ml*fJWGd6Y}<}h4DlHt6J zSIv{ld6bV=e4nRY3VwYFz$><;@U}AUePC$t71_+ZF%R@V|7QF^)B7(h(Yp|^cUkKF zzPPYkH9)Eb#mS!loRk`P$tbe?WWww+#JM>rH+{kpl1Bc%HM{solNNjLEiM9}@8@53 zda;JW>@m<`d9zFQ8eRH=D(-cYd1KZDJM0M1`HJplq=V(3_4-FRl_FDXa+q#MH#F9x za^h73bB4o$Fo$#Rc^W~CGl})$+O(?r(u7c`z6F|bEi>O8HzX7Nu6z*Zq)H$aGf#L^ z?;2(Zlz>Nzqz^5y1Jce zSFq;&E%qI3qqj_+f_>Ck^?h!W=>6)l)q z*u#Zf^;l8dbSprvJ)r0XIO$a&(&aTabjIdradBibRRad793v3{EJ4F*BC!= zRf!4foP|^xTj8{5MHBwaY|@~9G`Y()`qUJTEw{i7VBDKoqk? zbd%wp4s`4*n!gQi%_~c|IfwgPMl_gX`sOO9uNGc-Y5aQEll$M&xWqBa)!)4EYhO>) zM4+ke7@v5YM3u_RoBH#Ts@D?xpZJmhML@d0JsA}h;`U|3t0hG&W~nxBp3^Mw%g|Q~ zFP6}+CtpoHWI&o0mJM+ELq5FeVsF{Y0{dnaK78X!#D`|J9qzBNf6$>1JeVpH!un6oTgT+d4J3-7dWVX?4ZnHS+W$w??; zV;zVxN&19-F`dB4$BIV!IH-9!5fCfleuvTUIr{O z{BTHe#Oq^f`iG-)yf>?aEy~7F&2{*{jg}?iW&-;n*cg;-`XFHkk$&;LT1O|T8nUrb z!894=86GxT)!>Bz-s51dd;b+3@JIlF1yqz@GrZ;DtF6EB$Qk5%M&wdF>mh9NZM-?3 zdeB6Evsglsgp5kbEeCq4n9iTM;(D7E&BsZG@wkWJPYrn8JMX;Zt{P^1Y}8`aRRxAc|}961_Zt9WY(EQqmErT4T+Y0x0rYr#Gxh* z5U*(cD=EDwfD)Dvs*u*VRs2Gc(&#k971bFyZbGVO30}1A`p+R^Z3Gx$yYKm zL!RvkzBnglakiajTYFCGHIM@MwD-I5GcWdrFTNgrJ80V%u>9jNMK8YPP(<|a+1aPT z`>jvEXN(c)z`$Kkt71 zyHh)h%io^&ovNGs`a7eJe){yw?<5M30UI7J(}?@U%|bQ@ujIv1g=Lc9JoM|pWZ)a_DE;Y z)O|m|93Flx|L)U2um1e&?>FY$5elaNr}yt^l6!jf$Fz?6o=>5eYuZ&VO02v^fh7Du zk%$?UFh}0|jsN*13q^GeFgRn4_?`q1qkrY^-QidK@9yv~`nQA_bH8@~OG(8S7qMDY zR!Hr7e}82%QMc??-n{s$l3}|C-u3q+Qkhu*i~oKaY<=>cU;LN*`7QNGCa53Sk(IW} zgeJ@h%?X+kt3HKR6#b1j6hor$mj^%69H2p`6|(+_K8YO+cfYCj$IQ`vVwR4JQff7 zmg9ekZP?)1v7)v%L^8sq1TYNBB+eT?*Iq*rL&F9218%pd1pt)iyRqg^-dn2#sVA>$ zNAya`$SG(fo0-ZE?Y1QcKIKI<5@n9Gm4sAtIq1b6vJG=7O^m0_3Iudj)FRHF#1+FV z;%yNLJ zlXsr3PF@&oozk$^jT`|h)cdHodi?}+5f^DdE&tgH4u=GqdTerBsGEc5Xf}>{jM&mG z_YNQ$mz9>=7xs>A7HDdt>0~D7n{cv4?pmb8QDuQp^)(JJRg4eTOpB4V7#dfwGOYdJ zJ>oSebWt`L11?AMHn{|7|GFJMo|H`qY+yc4pbkqKHHh_p4Oh9wgIjGj)Iq80^Q0u4 z9K3>ztK=$Dwx+8{x#m9Gi>)xK~izt83AW7`!Y; z(HywwLv_}n)%Zm)D8(h)k0!Rc$t#tS5I5)6yQvifZJIyxXu>e{u>UXEY>0Dk>i?U| z(F|M2p=)K5T*PeI0gF7bS;YzV`8Q*DiRw>|UAk>Pz>kPYyb~3M0XAcs!M_F5Xjm8w zH2;-Aq467J=68G`6jxJCMO-(@)EhNOi@zDG!3&zm_U&dtY$*7dPey?~pZ&7(u*Yp{ zIJVhumI0cjN-L3pbS;>T=`nZ}#COE>>KEYF-)ISo@{}`nIzhohQ-j(~OV&9oRkYn& z@DhEu|Ft2OV=dUCiYaPmkU6XsRIRU zBLLl5x194+QsoUAhGXIm#X_#n)+0rN9Of=Hp&mKA~Sr zjBv_;Q?jtXzzp!~!tQv3dhB0D%CHbm=9^GJ;V9BxN=B_!b1Wd zN73Z2w#uhvTtwKOB@)-q1p^kIAnaU;n61%$-0)?0`6u(G;^0zkn55QAQ}k>%5Z`(O z%TSqRFd5|V-C$1xm~ef`xHpT<<`uQ1h^9tXYQT;;41?x|8io|&bC{%zriE-Q0Ksn4 z;MFdM4pGU6V@vo`&>4L~>lVys6(1#LLq=pHy8eOlx9ip738u zDo>^DmZV`3F|=r9EqWhKMuf(Sj0J2P{($_m>l>nay&14=AtSF_V@o<2xN>LQpl;v` zc|);bmk0EPU#ZaD{$aH0n}*?Jnnvmgk^a7EtVOml0ncNd}4j!B<+;BM-8(7<0Sm+D@_j40jcM#FLglHm@4 zt!1|>cEnOnmeXtsycpB$uO_Q;k$-X?VMo@f+G~wp&!%NBIlC^jB1E$tfwXRBS09=x z=1-K~EnkUfa7jA~d^oKbzOqqDD0klc6}xU&UWREFj+0r^kOiCb@IHiMNljZSwzRmd zH_WNU)YQOZQcGx^Z;{9v?)fEI2amQyL9ihyg(Jp6e|#Bx9#+dwFi^f2fCf_uPnA&h zfNcnSY!22|e-*sX&YBWfU0FRr#U+rwHK`*SPwjP;hG-BpN>8&Vw=uz)Oe8}53-ykM z7lM34#AB>i<4Q9{$P_s6!n7qzcNlX3qQ6;QmLm1nJI$<29o<>rEU9w%lujPb?AiT< zI6KX(qlIyq#K7JoPM^biv89@=3i+&DJP1fV&x61nHGtRk;JukY?f?DYdVkysW9uOeZA304FJ zA5<)k^3O=w$Ty;L5`W{_v#KiUH~Et%pMb_L2k)EB_poz57BKVi(0&82;=lR3X61uz zQr9)9k^o1+N^VT!ACFJpif7pmy?52g0xKb_rWJQBaoO56VF7*|@TsCLb^%-Fc~kYa zpui^f>`J4~KqaGRIL|Meh!)ue!c*2#fk~@ZMdzEZTO419!3{C&8kYnw!zj-kv-@a* zfbl1sjG~#s+7-GLL92cffwyx&T!~PvYfY*AlM5?6*gugP=QEm+F3emWV_)b5Jy9xQ zHDLhfR%L3!YK^5jMnh&C&8k73x_;oEf9@k#Xt>|o|GtlhqhtIW9KFHAN&j^Jmh6z4Kn{H3=bZ54hy&UM?2LH4aWay+PX$6}k zG!m?7F(U}GUWv%v`bb;~z6E^mAcG0h6F_>GtsI%lc+JvM=tp2_`Kic z#v@!7cLwZEMzI3j8B9C*vBASz$ROjAhAQ2$u{A3X9rY9XIO1kTAK}J=d@{j@43NPf z%|$gdSRvs$ci79=?XsrUi|EdJ%nt*%Pd?cuTyLy2JlY6K3t-|f7t zEQ(=7lHLr!LB#waY#_cCoa<&1pK`kfMW8}9iAUGA=X8;_H|LupjuETv@$hYJfv?^k zzBxbXH`W<0$J94n{5Si>ueq57vWa3KeMawvZZt+vfkgDoa@SqkJf@xuVuzUfNsCHE zvByDK&9LxQV!1e5Y$u|#!*QO?T5#eWXLF9u1MMpI_gQ74+DxI?uFGCj*|*rztB^2h zu3FXil?>BRhOD)*`IoW9a=vTHz_`tRnvIhSzE)<5k_jQIVHdI_O}ehhNs{76emN`i zE{7;ksYa|IEx(EHuA(^~tp&ft> z(O(ixx$DOe|5y*hDZ1Vv0&tZ{!M#?QPDDE^aotW*7aCEc1e3cd7QXHcY6#52Jx7mZ zlt0AwVv2y9E=u{__BVy?K&}gYaG8fn*k<>VpifR5TXLSQvn%@~%#=;0_QuUH_VtN;j@`YfU4MLoUoM*(&q~G>T9rEW z!*~cfBPOWL?<6zFHpPjBxus<%jL}qMK*E|91Zti@hHE;`#B;N)+;!Oo#oo96TK%U^ z$62fwMBtSZEKj~nm!G4EHX-POIK|KZic4BE7A!e~~UH^CdY> z61h75;ZV4WIsrt5J>>~VJ<%;6BzBaQR|ZBsvp}H}zf!{MI>C<;W@kPNd_M(Ml6IER z-{*UPteQn;DKYW{@N_Vk7kl-8%Iv?$y12|Y-QG2;8817*=FT@o<<+5%vwIl?uXvX! z0{>kf+Ug+i-fgrbXks#9%f;Z$KYJYb_B4i0$yI_geWyy)mm96ygrl(K@x``<^kB7| zx)y4MD%sJA8!h88fLTg2k?qp?NI#C#QM`qy>^r>W?Z}n~Poep=k|YRvy12XA0e$5_ zT^cIAkg#VIHj6mpgPqg@Y5o>4%tsKs1y+hy56?Xb{~oaD2)%xrmIe@Bs{KsTCDbQL zI>BEf-i<2(x#|IHHd>oIFP;-y-hGal_*OKBXYAbPed2GT1>j{tQo_z(_!HIcEy)Cw z_AjhEL1Jo}zj%r+rGD|PB-cFL{YSKSwf2caAT&0e>ZxD(*XGW*g_iwS+Q#M24UymB zMVVd#luMpT!mG;js;vlwzoGnX<}JiaXx^~imQ^hU|1MhpK{ZE>Dyj{0MCD}$@tuPq z&Pgb|sOTPi=4A4k$wpk1?dh1t;K0~!d3&&*OA@fiIi)2EsllGM8#7o8XpcT;XZXK0 zvOvxh2>pT`TQ?=LX_AgK=Ahd=){~A+>K_hUr^l@~{iEmjV;6tCz#m_=SbM`4O~u%{ z%y>~gpdiixD=`fyg<4iwVH>ab-fF~tSK?jk9a(96V>o=AfC~0$U|-l-B`mc~&CQpS z5xW>+R|B_!OUuxBaq_NbKNU+e$!@o?{QE4LG!rf$oXM?lYJNpprDYLXTv~gFY~SFzCmB|)Z*tlLO2Hoh;4x#V=oT--q-NQ^ zhxI{te*Ct7)GD&k*l1~(vn8@xXqvd2O(ar}?+!qMVAv_wCw$4^KxEDRsIv<~Qd|_F zE6aly;_`XY3~+O2rZ*fs$SQ6SFIr@qdH-vsqBdNTFwp|ry0wUH44(2GnWV>PtUIVQBk&dJ>WIlVUh-Ua<|#5e=yCp>FPZu zsi}vB5M?u0jVNkZn0e19+8V;?CWG|L?WLcN_SmazTx+eDAmlB!wX6t(42WR&+VIR~ zw_J^8uo*3%Kprz(k^@+6D1=$wLLmYY;#ZT6`d1P1YU}98rN2+eaxdetA-|NRwqEs) z-oo@r(b_ozk+o^sXuZlV=Y=2=*a2`?hk(vt8!^8SnwY^WWZ3s03?l3NDBpTgJY&v* z`D%0<-_dd!=YVQ2^(9b5lS^2F5V@1V!86*PiY$%9q-Ar?dkAi}WVSb?c&If7Q3KWi zAZFA(D>HFtq90~pbJ?t{*cvQ1FVwnqSf6pfJVDV(vkuOW(Iq2|EhWT-cZm0R;U^;o zmG~IvKoGrY8{ng3y_o~n)6Bn1ebZ`cvnM7w6t$hpe93d$o=1e zY!-8P#Y0ZInVPgLW#noJFNZzdEklXK;Nb|hw`wVy$@6XbfBeAzY@OiVSj>ZPM1w|> zR{@+Tcq8xxZh9Gt60yAR1`a5JZ85OY2ggT0oc0boHY+eWAIO|DBp}XRtX@?DwZ$V- zsv;c98OWuX!5>^Gcp&%H>e=V%Q?&nQr>|K+Y5%(9tC7@qcG9DD&@xV7Q!V7jmRv%UVJ zx`WEDitWY(?rGY}gbE*gm(cOF7)#S|B$0W#PErpQW~;G!yb=0r27L`g>g6P{`zsYg zly6g}o`MRTC%d?S8b?o9#!TbkDtq+3RNcV;U}r%_qLqGtSslqO$pudsRg@>XQ0ecA zp?m{jCl z#r{|1t<8g?v-{2ByKlZ;eD{~#7p=qS4tRC}i6M$v^uwXYv%5yzV9>{T`3M29is?wJ zhqf4{VhA$ot^qV$MOd?X=_@2IN9$+5L`8x#wD8P7CLAC6(hEc`=>;M5L=kSI3azen zXtCO7S9CsVhiG?_(Dn`nw;PBEPd{Q|0}iB)VmkU-JB6VZ55LnjT=z@t?$bpQoFFn1%w0 z+R9LgR7-%h=4=Sls@1olZJT4;vZn38Yonnh%@eZo6qg5GD?ZhdhQMNbQioP3v|lvU z{9z)%cK6ixlE`XR)|9-@@tZ{e&nU}UVEJ%$n0r9MmjKEp(lf$79L8VHLBPJhiXOfv8P#fVtbnZDm=m%$mH%Eh`H{HNO7>vd8IFGSTxCW{Y z=ekCvHEPiY${sT-&4MZm{THoFfhFSdfVHil-qX$wD?w!qEk z4u9GP(Qig)QYv2LXWpKZisr zvUFpeym|q2p%{rzC8JjyE6G&HOuI%#2A83*x#H=CUuAZEV@8CQXd=bIR^dq_&lX+( z3F=$_FPH@nOaimM&{Esb>KL>&+Ilzm^Pm45432*2y&D_^C%rd)yx6E_<#;F8>S9#s z7A;6(wQJ-{cSnXG@6imllHy-2O7gjwy|ewy&P#VUU@K_hi21#7=>S{6^}-GSGwgC) z=yU^v>eqC=Kj~Vi}QDKc-H;mgxXl7mr;9fe2w_ZhZ8wisL=*w8xM}TQM zP|mD}+_F@9OW~k2OgSz{4_j`yMqW7^pAS4-t`YQmL@nDoN0>W#kc?c_vi1w9qfMdE2Da$rk`Fsmokg_Q0!i*DvTD1 z1N7eJM~CjJvbNV$wc;=X!Dj_A8n{BZIPV@Po|uz%O=JzJJ41DeAagmm^*Rky~?4zX4ZMLVJa|@A2 z%*mY*vdl;uv?MTS^S-?@Yz+`mfM%XhwF4WK*))NrtMcR&aPE`%qLjU*B@Vsvo8hZ? zD%f?4A}R}bTiliRc!TfC{V)1e!lj8GmFcv_mT=3TVM-R}Yh>DN4G4m2+~xxY zz;4M3-I^j$B;m$OD1Z;$@xS}IH-DLVUR8w$*|K*dR^w@+s?N#t&Xez?iweffvQ3RO z#Dr?TKX07J?=O%4N2A_l9Lz83m*=f^qtm%;vuTyMG-$P;20_bLAXd&=`uJyxhOp^e znmtKeY_Pb=ECV7D`Cki2aj z@B-|VhIc~Ad`Of@4qEQ05-55-T0vCX+Z<43m;d+bpV5pS+=AON-b>*60dyhOq1o8m zimwGL`hf(jV+QhC!`CfW{L4&=IIuee6IzJHt4IVX2yo3Zhki=jo@YID;yDBvHuf;; zK;pfF>VvVkCWSp>6vLdPAE(I-&!Q0)oc{#R>*>!@*?DG~*9HYI=63>&E3t0~pKDYz z&Qa?8wO#N4=Q=ueh>L^Q-WC8_f zXt!_`#iZDTyD_!fRKb`Ui@#wO^#9>5ohk1=Lx&l0oHx3)__W<<k-UTgnowH!nb%?62>r$XTjgZ)bA)LnBZ=~d1%N35&0RH-+GbC^(}zR^Om-cht5A&;%; z2SC&G7BgmQG-lH^T=VGq|3mti_7?MWFWMH}wxGL1CfdF_d;o z3A(L{*B9$3?y10{_F411*^O%*m*jb~8Zg(jb!Z(<&uZUy;&!8Z)xO}5aqZ-!&4<>` zIQFbuS$pBasC*5G--xYsyD*ZkzEy?M9{4{*NwaZ)EuI zv*f`zx2X)-^8O|>Ma>1@#XMmT#Etez=&sB7zZjL#Bk7 z@(~&`;Zz=J50n=!Y<3uggvD+t6-ehEL5}6N%s72uQh;sG`$yY_9PkPO^B>RI|C2qi zCO6sq&=27EkvNsfLx(eyszAekg~d5x!7lbT3tA50+Zg*|0A6I=j~R18Iy1fN_kvL5(b60}51`;8}3@~8d zg$?+Z>m2j25Pa|*epMo9!Gq8&`Wt3~l^qr8PwvL1jay>FX5uGsj z_A(IOV>m?7cFodisg5xyG&c?;^vIldSjcG3q#KUPT*(l*H$%1g>O=ENR+ zzA{$~cLm29zFkZf_NbPZT{c|ZxNLmLhr%8cj`wE>-j6XEO=g z{gUCndHp5_zj#TSyv}b z?)D`_Ms{c$(_edgdv^zi%fEev-=$w|TktqV;^C8+XFjmEg4G__M>&@zZehX~?pb}B zPy#n%Osr)s0cuK{GF1fN+^8T<`*dC@FuSx%!6)aLTPI=RFSM^ZcgEZ6IwgvqWseYT z8kEckJ&B;f9GgIMCKP;<=hFuhWbhVeB?#|k=`Ylzvb*dfkS`%-mtN#!Irm8an z3yqCwE{Bq~hr?u=Au4YYGE@2?vdNbt*9329`BO3;tM}$K14dGWC@DtPeebznLMBmS z?I8*eha<#!GoB;*L%-Oj`>a1D^1(CVu}aU&Nt??>>*t`2enC#jUt*4cDL>)va1?GB z6gC-bW8xg>MMWeRf*>$MFq+4r(%28#zKzT_lFp$*_J**Dota0qorU6$U7tMw8DYI(;oPNS9GT6*@NSZ=lCGF?bX&Q* zz%2PX4+hLkY%-Z~uLnfSJ>pL46Q!`SgWjy#d_j8>*v0Evc5|oBs6GM~Xa&R)K=LFR2EFE0@l40}CUn!%F-2Gq&N+kA zNC$qA1@?BA<00QSMEbB|x)184N-YWzqY*YgP&)+Us&&TEZbS=cjA<28_wwZO>-U7X zTv-l7R}5u;KjI;AEG#kHRqRrtxbOqRBz`}vU}p2K53<+jJ$e;(eK4W!uuw6Uh)|qX zgCH#}po3gh#K-hhPOSpqpz^r1j;`p@k=1$3{O!G_8bs=JQ>r`U($Z$O1A_t20@CBC z3U#j+*^`uics+@d>&)|GD=qv7EyHynU&dcabh50PSYQ~sY*jHEwmv8QGuD-p-|Ps6 zpmYXbgJ=_vxp7WO^#TCiI&TK#Wv&LLpg!^h`e$*k3~$D=?Qwedz%Wg2cHEolTO7Tg z-u(Qk!X8%pl@mjhV`eea;#DXolG^i*vEK@C1EXh74gZyw96&{Kdd#7l=L{WbF4LUr z6Q@?7;#@kh_Ckp};3nMV3#yh^LC@Kua%CkCE9sV_c_&t&w-^R7raa)c(jV|80qF5! zIP|A-gDTt`fA-Z!!c6R7B2geVoM2mgRU5a@Y{LMbAsH@01&Ya_1zT zTD|xVKK9OTi@>t23Sk3)j)NE~xm{SkAx(Y)`tK`ACF30{&R&J+CfCH;jfIjo3a-FN zJ4k`U2T#m!IT6g=owZL{jQMJJ;nZU4;|$@1tljcd%rD^N%vMV#64%({n||?Wbn_N; zeNY7xyuMoO0^7*|Jw${&V3K{=3m1_iz1E~R7C%kKAO|)bgl}A;Zjma^3RyAzCVpG` z;Qc&|YS-X(2$y_x77FZP+bD)hbH^py1@qfowa@uHK~M37=V|oK>bG15IXgai7jNv8{G( zEKu2%fg9|Pe5Q-3&Ii#|4|fA%{SyxJz@#!)eYI7DYvYqt;8amL9Y_{TEvFK(Dfs)@ z*f>rxgqvA15|iwp=a6JrwW5H4oJ%Mw12$6gXlvCL0N@xzuT5w?n|lSO(!JRvOM6@S z3TBW&MZ`bU*xe-K}gm85XAjRI#9Xa z|K>lwd-Fg47tE=SEh>?_C(&NM#aL1Nl z%_coJo3G^GCiN6;KchPRCyirEAj!*MhUnd~N@S0k|M;hVM*F%P==eXrwI^gS=3Gg} z6X{R{X|T5?q|1M9Zj8}KVDljr)4oTUBXq4bgOZrLX6K7y3|^q7Vbx>9=xSJVI0>j8%fnTwUTzL~35^`arhm`EX z?A<|ACguX>`c67k1CMzQU=Xc`1e$sWffhLJ$VQLGaStYy6TKx_CUn4P;xAm(v7M#kmv*W}OdnPqC)I z;+K6m4`~7Z?SBnIMOb=>4hFFqJJd;yi^{zOPWQ{t(_{t%H2DH2wUTdsjIBQC@frN` zw)?9ZHWv#=dP*)rPY)=Zi+|@Fj^XFyPo6cu;+HXY7=ccUxmwP!BB)XzA z!fyy`Ub5Wg(`FIX%;pf(rFtk{77r`xG7s+k7d*o76^6$gUhq~2>%R%rFLJ~r{I*&MI zvRsdbNOgu!dwY8j@9W{`kMt^vo(Abq5E~y-dD&l#aIj~KaqvEyPvm6U>h_IUj@0`o zcc9#-Uhobk^xeEHxEu~yrwK0#h2_9T)c)uD(zjN1jcDyWim(r!nG8$12#vng!EQn zE#qV{zY|kAg~Av{^}4J;#!`6@q!ha!BeCCNNZ6tW?! z@pak*=?glAWuekZH9y`f%!byJJYU8#?v11cQ+s&tQ5Zt+#VC2?m^7>du)hwuPY~zt z?P;{JTqG)!YCH^?CSBvmZD!th(&F(n`n?n_OuH0-h!oKB+u0S_;eVy0Vy?DqlopSR zxTrW`-llns$~K`m<*TDB+&u7i<(XcMUS0%p8E(i&@A{(9oU~;_o2@y}|&ESjDqCvuw`XA&qqbl=- zS2JHcC|SP61-s!_wEa6{s3}53df{w0C0wh%k;4%b(pR>SxJHd9A)@$hSvQvUjxUR7 zCl3gl*`81ro;^r*$t2RJ*-`0?```=9JssRn=Id_`|K4M9HCX*s*PmBt`7NlnZ@&RC z5h^NzmLz}3zEw+TG7yKs9DvO;R7faKM`B6o)ni>Uz+D6eDHSy` zkpk1#BRR3JBEfIW^^{R?oAhGirg1x#(l(MInlm$g2F~{3l#?pU2x4|7mjv0)P(V(; zXDls&sJ$IN9<@uE|Y zX=;0WQHvg$NG-}L&F-WZ)m_v8g}`YoB(8=7#lKulI>fYGb1xjivda%L_hbgY^?O)C z4`71(cl>jG zn{2UdNzRgmW7QEZS%8ekrZUs}gUyP4MTd|ZsJ>;18BggKM;xIs?lk|_h)*xuafkkQ zX5^Ce)$rk)HenO88SuG*y%hAeKiUKh$MxHDBe)jVgwt+F!A;dDfX36Hctse;Pv7gCnF`Au)F!rbfDD{b$)3 zNR#&|sj5Yo3E5&;-Y(5QzaSOZD0VOqPu>AszIpFJzm2UQalX#d4J-AQReRwcm1%18 z1`7k11^a4iS$js3o8HPjt@$~G7TK!Y3?5md%V90GVD&8{(_G2?XG=8%pVW|o?Ms%{ z_X-uD;GUP95Ijf@=klSJlS>=Ep0noCfT`ptnMaNT3bK$8yry?Gfj;`lk_I89`VvXk-y5dUgzLTr-R^ue})1iTR zMq848Y6N2`czIs`oqrYm3#=h@I_?`Q;eO5zT0_jW8}x6banWtGV?@`xJpLcyQ(W(! zq439MyAfY?8f`pWT?CH+gcss~-n@L@q<>EcjQ>KSllpJ!mlqfI)m7t%u*`X_c@dv9 zJ~ZnM49yDWY(?1_1gM!)qW{?O@ZwVaQ%|n{(-=a$l>bICM1~vXIL4C#m zqd(}s`ytTJ>0Sx6-?oRJri2543ycrvG?`_oFb^C+jMWiY0?Vw~mMLyL)>x^4h&+Qy zUtFe;t9EN0RKJ=ntYIT1!>6<;0a-X;rbv;rsQm~B7Z`fNWhKcp*N8&!2S{gXqpBLm zDK|O!IwrVnX<;Jxm;e302-W^QA1HFt&#v281fxuPG9MC;Js zUQCsc%9}6i9MOi)(DaJIk2<6&I)Px4z9XI!OEoe{oI4%$IFjy>#MoM7^T|kaWFHBN zFjd%FM6J})88IC7Rvn$6COrOkA59q!#}CIPYbMy6_TY;(A%rwxJAUX3w+XkJ8Haut z;wNHNZ)ZtAHLU;!tD+8da$)Wiah)T6vsLNP@Q5HM690Mvvs`NsoAHO(d|-0ZIRx^z zTO=`0hCEqe;pqg@S{DXK2vbX)B4{!U_bhcgnD_2rdISG3*xOBpo_2IH6`MX{GA3{b z>qQsm%}QO0aa0?og_tivR;sGqGP(R!+DmPKx-FSR##u~F!~-jjH7>=Lz>c#X%;yiI z>!a;A-wuaA>_!jxMSt(~?@a&p`R`U)rDMtJy0Q}AbXCd8W<#lK zFb!8x(FQ`(6yG9(4)93k51?ZX>UPH8XtVb?kRG}4Q1~|QYq>Yh1tJRKQ#>8w@0Bf?^iaWD&9); z_xg$0b3qUQIh;VvD7VZlJSi3y3$d>vRZ(X{>a=@;S_V;>_<^s&)b^m{zEQ zQ?GEmF&hy&c=}u+Lja6sw+#4m1Px2;KSSEEq7N?;F^2Fq7K5umsW*F?A~ry|2%N(k z|As>Ct(W!|?8?fXo;2$1A6wmWaeeh)C$*=IR3f%7S#v9d7Yit_uxtq)uE;FBz+4<> zW2Jk%7oQU`JOEn4m8+3Fu~Qd_~Q*m^34-<~nh+@L}JZPGev%pFX6 zP&x;8vl;c>bTl8D*h;W%hnP{Y1%-wYR+9t z2u|Fxv#lS30qP!r@Q&EbS8_Vh&%jFz_`&>$ulvFJ65?^DD+rnxyPglzv4ih(vKH9g z;Px(l;7G^>SeG&*+I7$yn1D*zbD#?7BpcAo3}=fL$X?`eKfR}hN4GH> z500swex-#k(WJ+Sv9Dg>VYEhA>PD?vlXXA9%v%*a(Ly3X7uK)!;a%MQvDJvNL-v+` zZgo#u`WXx!-BHL;gKUfESH^@*C_DuClGh>=aF}wd@)u&qPS`Ru>MZE?LV&ajBGunk z2-CI1b#PDw9PKbDNgJo$uGdc>N_S|BU#EA;@P>U)A(?;AG;$6g%GO&Rz$r&MV++%* z?u2M(FN+bXB0=9m%)dpudd+ibM>;oX5$A)~cVrTcA@XBvzYh`dHisd-(5TF<4b$X? zYGmdk8^^jtshX36O|V7dWA9fVDi`sBS1TOLG>ly8v{l8emHws`WaFuK!jkg3AHynx zaaG;JCt{Axchhqqh%@i!R+l(-w;&gnfpXrSLH^pPC83q*t_WxuNKkMN#M{A0z^_xu zh6bcJXJ^Zs zgmzpAti|`z!|6n^)=Kk;Xv_)5y>92Izq2*VHJ-%Yz6*0@uB*#)U6>cF zt0pHlLOtgmtCOblg1KWGOiZ2$-+yRQuBZL)HtG$B=a~&;c3Q2os?z4v93*DBaYU3YlK@V&c$t;+bRn$GNwTC7={YxSh?^+pLb-W6jXU&^BBbj&Tbt zZD1mb!s7PMJnJ2=`W^IkDQFWk#Ne3R29eDy;>=()Wgw_g8p*+$O=gR8F=j~2l+-%N zq2^`J!IFtbOvC{zc9;QpwQIClIx(fIeVrn|FWaTlb_ti9tuPF8XI6`?r6lHv%R6hj z*80FHqiou8+6AtuWuR%%r*!p+=-wO0u9w8kuH}Hv=t9CxBU(ZpTZM4F`84OwZ|h}1 zIYPp{u|fy?7T`{y4f`gcHWQ!I`}poi!QaKxBfljdIWoS~+2Vd47P17-^I;D|G?YYj zB3n4ky4hc>TtpZ+P29xe_XJ>oDq(&2B#fg+@C3H_Z#%yEXo>*bn~#?jP5)o(*wWLn z^J+ax439k1Y8)R?5>|0$a~6hsFChcJMRYcz4I~nM->tjfCl;W@l4dHT-eP88avykt zMTjR(eq#KSC%a7MxwckS9X%BEezk*vz>&x7&H^ZRZM2<8~jzo

h<2}DVwp&CHEulC0rM~E-_zNBQb?5* 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 Q|IqXQ0B1QwPXL}008;?Gj{pDw literal 0 HcmV?d00001 From 16c753c6750b077504e0263c315239ba7b3c3d8f Mon Sep 17 00:00:00 2001 From: Alexis Charveriat Date: Thu, 12 Dec 2024 10:12:52 +0100 Subject: [PATCH 41/48] Additional stats fields for Elasticsearch (#41944) * Perform an additional _settings API call for Elasticsearch module * Added filter_path for cluster state & index settings fetch * Added index creation version --- CHANGELOG.next.asciidoc | 1 + metricbeat/docs/fields.asciidoc | 21 ++++ .../elasticsearch/cluster_stats/data.go | 2 +- .../module/elasticsearch/elasticsearch.go | 34 +++++- metricbeat/module/elasticsearch/fields.go | 2 +- .../elasticsearch/index/_meta/data.json | 3 + .../elasticsearch/index/_meta/fields.yml | 6 + metricbeat/module/elasticsearch/index/data.go | 105 ++++++++++++++++-- metricbeat/tests/system/test_base.py | 2 +- 9 files changed, 163 insertions(+), 13 deletions(-) diff --git a/CHANGELOG.next.asciidoc b/CHANGELOG.next.asciidoc index 20a6d840a7fb..22148d5a4f41 100644 --- a/CHANGELOG.next.asciidoc +++ b/CHANGELOG.next.asciidoc @@ -416,6 +416,7 @@ https://github.com/elastic/beats/compare/v8.8.1\...main[Check the HEAD diff] - Only watch metadata for ReplicaSets in metricbeat k8s module {pull}41289[41289] - Add support for region/zone for Vertex AI service in GCP module {pull}41551[41551] - Add support for location label as an optional configuration parameter in GCP metrics metricset. {issue}41550[41550] {pull}41626[41626] +- Added `tier_preference`, `creation_date` and `version` fields to the `elasticsearch.index` metricset. {pull}41944[41944] *Metricbeat* - Add benchmark module {pull}41801[41801] diff --git a/metricbeat/docs/fields.asciidoc b/metricbeat/docs/fields.asciidoc index 5f9ee24aa8c0..967c20f14cfa 100644 --- a/metricbeat/docs/fields.asciidoc +++ b/metricbeat/docs/fields.asciidoc @@ -32161,6 +32161,27 @@ type: keyword -- +*`elasticsearch.index.tier_preference`*:: ++ +-- +type: keyword + +-- + +*`elasticsearch.index.creation_date`*:: ++ +-- +type: date + +-- + +*`elasticsearch.index.version`*:: ++ +-- +type: keyword + +-- + *`elasticsearch.index.name`*:: + -- diff --git a/metricbeat/module/elasticsearch/cluster_stats/data.go b/metricbeat/module/elasticsearch/cluster_stats/data.go index 4fe1d03f6d73..cfd89ce46c03 100644 --- a/metricbeat/module/elasticsearch/cluster_stats/data.go +++ b/metricbeat/module/elasticsearch/cluster_stats/data.go @@ -231,7 +231,7 @@ func eventMapping(r mb.ReporterV2, httpClient *helper.HTTP, info elasticsearch.I } clusterStateMetrics := []string{"version", "master_node", "nodes", "routing_table"} - clusterState, err := elasticsearch.GetClusterState(httpClient, httpClient.GetURI(), clusterStateMetrics) + clusterState, err := elasticsearch.GetClusterState(httpClient, httpClient.GetURI(), clusterStateMetrics, []string{}) if err != nil { return fmt.Errorf("failed to get cluster state from Elasticsearch: %w", err) } diff --git a/metricbeat/module/elasticsearch/elasticsearch.go b/metricbeat/module/elasticsearch/elasticsearch.go index 446a2d128bbf..7e9f22152342 100644 --- a/metricbeat/module/elasticsearch/elasticsearch.go +++ b/metricbeat/module/elasticsearch/elasticsearch.go @@ -288,13 +288,21 @@ func GetLicense(http *helper.HTTP, resetURI string) (*License, error) { } // GetClusterState returns cluster state information. -func GetClusterState(http *helper.HTTP, resetURI string, metrics []string) (mapstr.M, error) { +func GetClusterState(http *helper.HTTP, resetURI string, metrics []string, filterPaths []string) (mapstr.M, error) { + queryParams := []string{"local=true"} clusterStateURI := "_cluster/state" if len(metrics) > 0 { clusterStateURI += "/" + strings.Join(metrics, ",") } - content, err := fetchPath(http, resetURI, clusterStateURI, "local=true") + if len(filterPaths) > 0 { + filterPathQueryParam := "filter_path=" + strings.Join(filterPaths, ",") + queryParams = append(queryParams, filterPathQueryParam) + } + + queryString := strings.Join(queryParams, "&") + + content, err := fetchPath(http, resetURI, clusterStateURI, queryString) if err != nil { return nil, err } @@ -304,6 +312,28 @@ func GetClusterState(http *helper.HTTP, resetURI string, metrics []string) (maps return clusterState, err } +func GetIndexSettings(http *helper.HTTP, resetURI string, indexPattern string, filterPaths []string) (mapstr.M, error) { + + queryParams := []string{"local=true", "expand_wildcards=hidden,all"} + indicesSettingsURI := indexPattern + "/_settings" + + if len(filterPaths) > 0 { + filterPathQueryParam := "filter_path=" + strings.Join(filterPaths, ",") + queryParams = append(queryParams, filterPathQueryParam) + } + + queryString := strings.Join(queryParams, "&") + + content, err := fetchPath(http, resetURI, indicesSettingsURI, queryString) + if err != nil { + return nil, err + } + + var indicesSettings map[string]interface{} + err = json.Unmarshal(content, &indicesSettings) + return indicesSettings, err +} + // GetClusterSettingsWithDefaults returns cluster settings. func GetClusterSettingsWithDefaults(http *helper.HTTP, resetURI string, filterPaths []string) (mapstr.M, error) { return GetClusterSettings(http, resetURI, true, filterPaths) diff --git a/metricbeat/module/elasticsearch/fields.go b/metricbeat/module/elasticsearch/fields.go index 7fe1827b3ceb..5f899fdd0aac 100644 --- a/metricbeat/module/elasticsearch/fields.go +++ b/metricbeat/module/elasticsearch/fields.go @@ -32,5 +32,5 @@ func init() { // AssetElasticsearch returns asset data. // This is the base64 encoded zlib format compressed contents of module/elasticsearch. func AssetElasticsearch() string { - return "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" + return "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" } diff --git a/metricbeat/module/elasticsearch/index/_meta/data.json b/metricbeat/module/elasticsearch/index/_meta/data.json index 2fa8eeb4f18f..3b0dee2f9e24 100644 --- a/metricbeat/module/elasticsearch/index/_meta/data.json +++ b/metricbeat/module/elasticsearch/index/_meta/data.json @@ -144,6 +144,9 @@ } }, "status": "green", + "tier_preference": "data_content", + "creation_date": 1731657995821, + "version": "8505000", "hidden": true, "shards": { "total": 1, diff --git a/metricbeat/module/elasticsearch/index/_meta/fields.yml b/metricbeat/module/elasticsearch/index/_meta/fields.yml index 8182963959b3..ca1fdecff8d2 100644 --- a/metricbeat/module/elasticsearch/index/_meta/fields.yml +++ b/metricbeat/module/elasticsearch/index/_meta/fields.yml @@ -17,6 +17,12 @@ type: keyword - name: status type: keyword + - name: tier_preference + type: keyword + - name: creation_date + type: date + - name: version + type: keyword - name: name type: keyword description: > diff --git a/metricbeat/module/elasticsearch/index/data.go b/metricbeat/module/elasticsearch/index/data.go index d8bec4939d62..ce5fa82e4ac3 100644 --- a/metricbeat/module/elasticsearch/index/data.go +++ b/metricbeat/module/elasticsearch/index/data.go @@ -20,6 +20,7 @@ package index import ( "encoding/json" "fmt" + "strconv" "github.com/joeshaw/multierror" @@ -40,9 +41,12 @@ type Index struct { Primaries primaries `json:"primaries"` Total total `json:"total"` - Index string `json:"index"` - Status string `json:"status"` - Shards shardStats `json:"shards"` + Index string `json:"index"` + Status string `json:"status"` + TierPreference string `json:"tier_preference"` + CreationDate int `json:"creation_date"` + Version string `json:"version"` + Shards shardStats `json:"shards"` } type primaries struct { @@ -180,11 +184,19 @@ type bulkStats struct { func eventsMapping(r mb.ReporterV2, httpClient *helper.HTTP, info elasticsearch.Info, content []byte, isXpack bool) error { clusterStateMetrics := []string{"routing_table"} - clusterState, err := elasticsearch.GetClusterState(httpClient, httpClient.GetURI(), clusterStateMetrics) + clusterStateFilterPaths := []string{"routing_table"} + clusterState, err := elasticsearch.GetClusterState(httpClient, httpClient.GetURI(), clusterStateMetrics, clusterStateFilterPaths) if err != nil { return fmt.Errorf("failure retrieving cluster state from Elasticsearch: %w", err) } + indicesSettingsPattern := "*,.*" + indicesSettingsFilterPaths := []string{"*.settings.index.creation_date", "*.settings.index.**._tier_preference", "*.settings.index.version.created"} + indicesSettings, err := elasticsearch.GetIndexSettings(httpClient, httpClient.GetURI(), indicesSettingsPattern, indicesSettingsFilterPaths) + if err != nil { + return fmt.Errorf("failure retrieving index settings from Elasticsearch: %w", err) + } + var indicesStats stats if err := parseAPIResponse(content, &indicesStats); err != nil { return fmt.Errorf("failure parsing Indices Stats Elasticsearch API response: %w", err) @@ -204,6 +216,12 @@ func eventsMapping(r mb.ReporterV2, httpClient *helper.HTTP, info elasticsearch. continue } + err = addIndexSettings(&idx, indicesSettings) + if err != nil { + errs = append(errs, fmt.Errorf("failure adding index settings: %w", err)) + continue + } + event.ModuleFields.Put("cluster.id", info.ClusterID) event.ModuleFields.Put("cluster.name", info.ClusterName) @@ -271,6 +289,63 @@ func addClusterStateFields(idx *Index, clusterState mapstr.M) error { return nil } +func addIndexSettings(idx *Index, indicesSettings mapstr.M) error { + + // Recover the index settings for our specific index + indexSettingsValue, err := indicesSettings.GetValue(idx.Index) + if err != nil { + return fmt.Errorf("failed to get index settings for index %s: %w", idx.Index, err) + } + + indexSettings, ok := indexSettingsValue.(map[string]interface{}) + if !ok { + return fmt.Errorf("index settings is not a map for index: %s", idx.Index) + } + + indexCreationDate, err := getIndexSettingForIndex(indexSettings, idx.Index, "index.creation_date") + if err != nil { + return fmt.Errorf("failed to get index creation date: %w", err) + } + + idx.CreationDate, err = strconv.Atoi(indexCreationDate) + if err != nil { + return fmt.Errorf("failed to convert index creation date to int: %w", err) + } + + indexTierPreference, err := getIndexSettingForIndex(indexSettings, idx.Index, "index.routing.allocation.require._tier_preference") + if err != nil { + indexTierPreference, err = getIndexSettingForIndex(indexSettings, idx.Index, "index.routing.allocation.include._tier_preference") + if err != nil { + return fmt.Errorf("failed to get index tier preference: %w", err) + } + } + + idx.TierPreference = indexTierPreference + + indexVersion, err := getIndexSettingForIndex(indexSettings, idx.Index, "index.version.created") + if err != nil { + return fmt.Errorf("failed to get index version: %w", err) + } + + idx.Version = indexVersion + + return nil +} + +func getIndexSettingForIndex(indexSettings mapstr.M, index, settingKey string) (string, error) { + fieldKey := "settings." + settingKey + value, err := indexSettings.GetValue(fieldKey) + if err != nil { + return "", fmt.Errorf("'"+fieldKey+"': %w", err) + } + + setting, ok := value.(string) + if !ok { + return "", elastic.MakeErrorForMissingField(fieldKey, elastic.Elasticsearch) + } + return setting, nil +} + func getClusterStateMetricForIndex(clusterState mapstr.M, index, metricKey string) (mapstr.M, error) { fieldKey := metricKey + ".indices." + index value, err := clusterState.GetValue(fieldKey) @@ -308,8 +383,15 @@ func getIndexStatus(shards map[string]interface{}) (string, error) { shard := mapstr.M(s) - isPrimary := shard["primary"].(bool) - state := shard["state"].(string) + isPrimary, ok := shard["primary"].(bool) + if !ok { + return "", fmt.Errorf("%v.shards[%v].primary is not a boolean", indexName, shardIdx) + } + + state, ok := shard["state"].(string) + if !ok { + return "", fmt.Errorf("%v.shards[%v].state is not a string", indexName, shardIdx) + } if isPrimary { areAllPrimariesStarted = areAllPrimariesStarted && (state == "STARTED") @@ -357,8 +439,15 @@ func getIndexShardStats(shards mapstr.M) (*shardStats, error) { shard := mapstr.M(s) - isPrimary := shard["primary"].(bool) - state := shard["state"].(string) + isPrimary, ok := shard["primary"].(bool) + if !ok { + return nil, fmt.Errorf("%v.shards[%v].primary is not a boolean", indexName, shardIdx) + } + + state, ok := shard["state"].(string) + if !ok { + return nil, fmt.Errorf("%v.shards[%v].state is not a string", indexName, shardIdx) + } if isPrimary { primaries++ diff --git a/metricbeat/tests/system/test_base.py b/metricbeat/tests/system/test_base.py index 5a5f1583203e..edee856d1144 100644 --- a/metricbeat/tests/system/test_base.py +++ b/metricbeat/tests/system/test_base.py @@ -59,7 +59,7 @@ def test_index_management(self): assert len(es.cat.templates(name='metricbeat-*', h='name')) > 0 @unittest.skipUnless(INTEGRATION_TESTS, "integration test") - @pytest.mark.timeout(8*60, func_only=True) + @pytest.mark.timeout(8 * 60, func_only=True) def test_dashboards(self): """ Test that the dashboards can be loaded with `setup --dashboards` From 08b7d84d4ab66ff988652a607a837bf93dc35e4f Mon Sep 17 00:00:00 2001 From: Chris Berkhout Date: Thu, 12 Dec 2024 10:14:46 +0100 Subject: [PATCH 42/48] .../input/entityanalytics/provider/okta: Rate limiting fix, improvements (#41977) - Fix a bug in the stopping of requests when `x-rate-limit-remaining: 0`. - Add a deadline so long waits return immediately as errors. - Add an option to set a fixed request rate. --- CHANGELOG.next.asciidoc | 2 + .../inputs/input-entity-analytics.asciidoc | 18 ++- .../entityanalytics/provider/okta/conf.go | 4 + .../provider/okta/internal/okta/okta.go | 36 ++--- .../provider/okta/internal/okta/okta_test.go | 54 +++---- .../okta/internal/okta/ratelimiter.go | 114 +++++++++++--- .../okta/internal/okta/ratelimiter_test.go | 143 ++++++++++++++---- .../entityanalytics/provider/okta/okta.go | 16 +- .../provider/okta/okta_test.go | 2 +- 9 files changed, 282 insertions(+), 107 deletions(-) diff --git a/CHANGELOG.next.asciidoc b/CHANGELOG.next.asciidoc index 22148d5a4f41..6840ef4ed533 100644 --- a/CHANGELOG.next.asciidoc +++ b/CHANGELOG.next.asciidoc @@ -193,6 +193,7 @@ https://github.com/elastic/beats/compare/v8.8.1\...main[Check the HEAD diff] - Fix handling of http_endpoint request exceeding memory limits. {issue}41764[41764] {pull}41765[41765] - Rate limiting fixes in the Okta provider of the Entity Analytics input. {issue}40106[40106] {pull}41583[41583] - Redact authorization headers in HTTPJSON debug logs. {pull}41920[41920] +- Further rate limiting fix in the Okta provider of the Entity Analytics input. {issue}40106[40106] {pull}41977[41977] *Heartbeat* @@ -365,6 +366,7 @@ https://github.com/elastic/beats/compare/v8.8.1\...main[Check the HEAD diff] - Add support for SSL and Proxy configurations for websoket type in streaming input. {pull}41934[41934] - AWS S3 input registry cleanup for untracked s3 objects. {pull}41694[41694] - The environment variable `BEATS_AZURE_EVENTHUB_INPUT_TRACING_ENABLED: true` enables internal logs tracer for the azure-eventhub input. {issue}41931[41931] {pull}41932[41932] +- Rate limiting operability improvements in the Okta provider of the Entity Analytics input. {issue}40106[40106] {pull}41977[41977] *Auditbeat* diff --git a/x-pack/filebeat/docs/inputs/input-entity-analytics.asciidoc b/x-pack/filebeat/docs/inputs/input-entity-analytics.asciidoc index b4b701d3919d..faa50cf732d9 100644 --- a/x-pack/filebeat/docs/inputs/input-entity-analytics.asciidoc +++ b/x-pack/filebeat/docs/inputs/input-entity-analytics.asciidoc @@ -1015,7 +1015,21 @@ shorter than the full synchronization interval (`sync_interval`). Expressed as a duration string (e.g., 1m, 3h, 24h). Defaults to `15m` (15 minutes). [float] -==== `tracer.enabled` +===== `limit_window` + +The time between Okta API rate limit resets. +Expressed as a duration string (e.g., 1m, 3h, 24h). Defaults to `1m` (1 minute). + +[float] +===== `limit_fixed` + +The number of requests to allow in each limit window, if set. +This parameter should only be set in exceptional cases. When it is set, rate +limit information in API responses will be ignored in favor of the fixed limit. +The limit is applied separately to each endopint. Defaults to unset. + +[float] +===== `tracer.enabled` It is possible to log HTTP requests and responses to the Okta API to a local file-system for debugging configurations. This option is enabled by setting `tracer.enabled` to true and setting the `tracer.filename` value. @@ -1025,7 +1039,7 @@ to false without unsetting the filename option. Enabling this option compromises security and should only be used for debugging. [float] -==== `tracer.filename` +===== `tracer.filename` To differentiate the trace files generated from different input instances, a placeholder `*` can be added to the filename and will be replaced with the input instance id. For Example, `http-request-trace-*.ndjson`. diff --git a/x-pack/filebeat/input/entityanalytics/provider/okta/conf.go b/x-pack/filebeat/input/entityanalytics/provider/okta/conf.go index 41a3895a70d2..61a61aed25e1 100644 --- a/x-pack/filebeat/input/entityanalytics/provider/okta/conf.go +++ b/x-pack/filebeat/input/entityanalytics/provider/okta/conf.go @@ -68,6 +68,10 @@ type conf struct { // API limit resets. LimitWindow time.Duration `config:"limit_window"` + // LimitFixed is a number of requests to allow in each LimitWindow, + // overriding the guidance in API responses. + LimitFixed *int `config:"limit_fixed"` + // Request is the configuration for establishing // HTTP requests to the API. Request *requestConfig `config:"request"` diff --git a/x-pack/filebeat/input/entityanalytics/provider/okta/internal/okta/okta.go b/x-pack/filebeat/input/entityanalytics/provider/okta/internal/okta/okta.go index 42ffc0601784..b2bacba89a8c 100644 --- a/x-pack/filebeat/input/entityanalytics/provider/okta/internal/okta/okta.go +++ b/x-pack/filebeat/input/entityanalytics/provider/okta/internal/okta/okta.go @@ -185,13 +185,13 @@ func (o Response) String() string { // Parts of the response may be omitted using the omit parameter. // // The provided rate limiter must allow at least request and will be updated with the -// response's X-Rate-Limit headers considering the rate limit window time. Details -// for rate limits are available at https://help.okta.com/en-us/Content/Topics/Security/API-rate-limits.htm +// response's X-Rate-Limit headers. Details for rate limits are available at +// https://help.okta.com/en-us/Content/Topics/Security/API-rate-limits.htm // and account rate limits and windows can be seen on the Okta admin dashboard at // https://${yourOktaDomain}/reports/rate-limit. // // See https://developer.okta.com/docs/reference/api/users/#list-users for details. -func GetUserDetails(ctx context.Context, cli *http.Client, host, key, user string, query url.Values, omit Response, lim RateLimiter, window time.Duration, log *logp.Logger) ([]User, http.Header, error) { +func GetUserDetails(ctx context.Context, cli *http.Client, host, key, user string, query url.Values, omit Response, lim *RateLimiter, log *logp.Logger) ([]User, http.Header, error) { var endpoint, path string if user == "" { endpoint = "/api/v1/users" @@ -207,7 +207,7 @@ func GetUserDetails(ctx context.Context, cli *http.Client, host, key, user strin Path: path, RawQuery: query.Encode(), } - return getDetails[User](ctx, cli, u, endpoint, key, user == "", omit, lim, window, log) + return getDetails[User](ctx, cli, u, endpoint, key, user == "", omit, lim, log) } // GetUserFactors returns Okta group roles using the groups API endpoint. host is the @@ -216,7 +216,7 @@ func GetUserDetails(ctx context.Context, cli *http.Client, host, key, user strin // See GetUserDetails for details of the query and rate limit parameters. // // See https://developer.okta.com/docs/api/openapi/okta-management/management/tag/UserFactor/#tag/UserFactor/operation/listFactors. -func GetUserFactors(ctx context.Context, cli *http.Client, host, key, user string, lim RateLimiter, window time.Duration, log *logp.Logger) ([]Factor, http.Header, error) { +func GetUserFactors(ctx context.Context, cli *http.Client, host, key, user string, lim *RateLimiter, log *logp.Logger) ([]Factor, http.Header, error) { if user == "" { return nil, nil, errors.New("no user specified") } @@ -229,7 +229,7 @@ func GetUserFactors(ctx context.Context, cli *http.Client, host, key, user strin Host: host, Path: path, } - return getDetails[Factor](ctx, cli, u, endpoint, key, true, OmitNone, lim, window, log) + return getDetails[Factor](ctx, cli, u, endpoint, key, true, OmitNone, lim, log) } // GetUserRoles returns Okta group roles using the groups API endpoint. host is the @@ -238,7 +238,7 @@ func GetUserFactors(ctx context.Context, cli *http.Client, host, key, user strin // See GetUserDetails for details of the query and rate limit parameters. // // See https://developer.okta.com/docs/api/openapi/okta-management/management/tag/RoleAssignmentBGroup/#tag/RoleAssignmentBGroup/operation/listGroupAssignedRoles. -func GetUserRoles(ctx context.Context, cli *http.Client, host, key, user string, lim RateLimiter, window time.Duration, log *logp.Logger) ([]Role, http.Header, error) { +func GetUserRoles(ctx context.Context, cli *http.Client, host, key, user string, lim *RateLimiter, log *logp.Logger) ([]Role, http.Header, error) { if user == "" { return nil, nil, errors.New("no user specified") } @@ -251,7 +251,7 @@ func GetUserRoles(ctx context.Context, cli *http.Client, host, key, user string, Host: host, Path: path, } - return getDetails[Role](ctx, cli, u, endpoint, key, true, OmitNone, lim, window, log) + return getDetails[Role](ctx, cli, u, endpoint, key, true, OmitNone, lim, log) } // GetUserGroupDetails returns Okta group details using the users API endpoint. host is the @@ -260,7 +260,7 @@ func GetUserRoles(ctx context.Context, cli *http.Client, host, key, user string, // See GetUserDetails for details of the query and rate limit parameters. // // See https://developer.okta.com/docs/reference/api/users/#request-parameters-8 (no anchor exists on the page for this endpoint) for details. -func GetUserGroupDetails(ctx context.Context, cli *http.Client, host, key, user string, lim RateLimiter, window time.Duration, log *logp.Logger) ([]Group, http.Header, error) { +func GetUserGroupDetails(ctx context.Context, cli *http.Client, host, key, user string, lim *RateLimiter, log *logp.Logger) ([]Group, http.Header, error) { if user == "" { return nil, nil, errors.New("no user specified") } @@ -273,7 +273,7 @@ func GetUserGroupDetails(ctx context.Context, cli *http.Client, host, key, user Host: host, Path: path, } - return getDetails[Group](ctx, cli, u, endpoint, key, true, OmitNone, lim, window, log) + return getDetails[Group](ctx, cli, u, endpoint, key, true, OmitNone, lim, log) } // GetGroupRoles returns Okta group roles using the groups API endpoint. host is the @@ -282,7 +282,7 @@ func GetUserGroupDetails(ctx context.Context, cli *http.Client, host, key, user // See GetUserDetails for details of the query and rate limit parameters. // // See https://developer.okta.com/docs/api/openapi/okta-management/management/tag/RoleAssignmentBGroup/#tag/RoleAssignmentBGroup/operation/listGroupAssignedRoles. -func GetGroupRoles(ctx context.Context, cli *http.Client, host, key, group string, lim RateLimiter, window time.Duration, log *logp.Logger) ([]Role, http.Header, error) { +func GetGroupRoles(ctx context.Context, cli *http.Client, host, key, group string, lim *RateLimiter, log *logp.Logger) ([]Role, http.Header, error) { if group == "" { return nil, nil, errors.New("no group specified") } @@ -295,7 +295,7 @@ func GetGroupRoles(ctx context.Context, cli *http.Client, host, key, group strin Host: host, Path: path, } - return getDetails[Role](ctx, cli, u, endpoint, key, true, OmitNone, lim, window, log) + return getDetails[Role](ctx, cli, u, endpoint, key, true, OmitNone, lim, log) } // GetDeviceDetails returns Okta device details using the list devices API endpoint. host is the @@ -305,7 +305,7 @@ func GetGroupRoles(ctx context.Context, cli *http.Client, host, key, group strin // See GetUserDetails for details of the query and rate limit parameters. // // See https://developer.okta.com/docs/api/openapi/okta-management/management/tag/Device/#tag/Device/operation/listDevices for details. -func GetDeviceDetails(ctx context.Context, cli *http.Client, host, key, device string, query url.Values, lim RateLimiter, window time.Duration, log *logp.Logger) ([]Device, http.Header, error) { +func GetDeviceDetails(ctx context.Context, cli *http.Client, host, key, device string, query url.Values, lim *RateLimiter, log *logp.Logger) ([]Device, http.Header, error) { var endpoint string var path string if device == "" { @@ -322,7 +322,7 @@ func GetDeviceDetails(ctx context.Context, cli *http.Client, host, key, device s Path: path, RawQuery: query.Encode(), } - return getDetails[Device](ctx, cli, u, endpoint, key, device == "", OmitNone, lim, window, log) + return getDetails[Device](ctx, cli, u, endpoint, key, device == "", OmitNone, lim, log) } // GetDeviceUsers returns Okta user details for users associated with the provided device identifier @@ -332,7 +332,7 @@ func GetDeviceDetails(ctx context.Context, cli *http.Client, host, key, device s // See GetUserDetails for details of the query and rate limit parameters. // // See https://developer.okta.com/docs/api/openapi/okta-management/management/tag/Device/#tag/Device/operation/listDeviceUsers for details. -func GetDeviceUsers(ctx context.Context, cli *http.Client, host, key, device string, query url.Values, omit Response, lim RateLimiter, window time.Duration, log *logp.Logger) ([]User, http.Header, error) { +func GetDeviceUsers(ctx context.Context, cli *http.Client, host, key, device string, query url.Values, omit Response, lim *RateLimiter, log *logp.Logger) ([]User, http.Header, error) { if device == "" { // No user associated with a null device. Not an error. return nil, nil, nil @@ -347,7 +347,7 @@ func GetDeviceUsers(ctx context.Context, cli *http.Client, host, key, device str Path: path, RawQuery: query.Encode(), } - du, h, err := getDetails[devUser](ctx, cli, u, endpoint, key, true, omit, lim, window, log) + du, h, err := getDetails[devUser](ctx, cli, u, endpoint, key, true, omit, lim, log) if err != nil { return nil, h, err } @@ -372,7 +372,7 @@ type devUser struct { // for the specific user are returned, otherwise a list of all users is returned. // // See GetUserDetails for details of the query and rate limit parameters. -func getDetails[E entity](ctx context.Context, cli *http.Client, u *url.URL, endpoint string, key string, all bool, omit Response, lim RateLimiter, window time.Duration, log *logp.Logger) ([]E, http.Header, error) { +func getDetails[E entity](ctx context.Context, cli *http.Client, u *url.URL, endpoint string, key string, all bool, omit Response, lim *RateLimiter, log *logp.Logger) ([]E, http.Header, error) { url := u.String() req, err := http.NewRequestWithContext(ctx, http.MethodGet, url, nil) if err != nil { @@ -395,7 +395,7 @@ func getDetails[E entity](ctx context.Context, cli *http.Client, u *url.URL, end return nil, nil, err } defer resp.Body.Close() - err = lim.Update(endpoint, resp.Header, window, log) + err = lim.Update(endpoint, resp.Header, log) if err != nil { io.Copy(io.Discard, resp.Body) return nil, nil, err diff --git a/x-pack/filebeat/input/entityanalytics/provider/okta/internal/okta/okta_test.go b/x-pack/filebeat/input/entityanalytics/provider/okta/internal/okta/okta_test.go index 45b1b2a4ca4c..d362d72f3910 100644 --- a/x-pack/filebeat/input/entityanalytics/provider/okta/internal/okta/okta_test.go +++ b/x-pack/filebeat/input/entityanalytics/provider/okta/internal/okta/okta_test.go @@ -44,14 +44,14 @@ func Test(t *testing.T) { t.Skip("okta tests require ${OKTA_TOKEN} to be set") } - // Make a global limiter - limiter := NewRateLimiter() - // There are a variety of windows, the most conservative is one minute. // The rate limit will be adjusted on the second call to the API if // window is actually used to rate limit calculations. const window = time.Minute + // Make a global limiter + limiter := NewRateLimiter(window, nil) + for _, omit := range []Response{ OmitNone, OmitCredentials, @@ -65,7 +65,7 @@ func Test(t *testing.T) { t.Run("me", func(t *testing.T) { query := make(url.Values) query.Set("limit", "200") - users, _, err := GetUserDetails(context.Background(), http.DefaultClient, host, key, "me", query, omit, limiter, window, logger) + users, _, err := GetUserDetails(context.Background(), http.DefaultClient, host, key, "me", query, omit, limiter, logger) if err != nil { t.Fatalf("unexpected error: %v", err) } @@ -94,7 +94,7 @@ func Test(t *testing.T) { t.Run("my_groups", func(t *testing.T) { query := make(url.Values) query.Set("limit", "200") - groups, _, err := GetUserGroupDetails(context.Background(), http.DefaultClient, host, key, me.ID, limiter, window, logger) + groups, _, err := GetUserGroupDetails(context.Background(), http.DefaultClient, host, key, me.ID, limiter, logger) if err != nil { t.Fatalf("unexpected error: %v", err) } @@ -119,7 +119,7 @@ func Test(t *testing.T) { t.Run("my_roles", func(t *testing.T) { query := make(url.Values) query.Set("limit", "200") - roles, _, err := GetUserRoles(context.Background(), http.DefaultClient, host, key, me.ID, limiter, window, logger) + roles, _, err := GetUserRoles(context.Background(), http.DefaultClient, host, key, me.ID, limiter, logger) if err != nil { t.Fatalf("unexpected error: %v", err) } @@ -144,7 +144,7 @@ func Test(t *testing.T) { t.Run("my_factors", func(t *testing.T) { query := make(url.Values) query.Set("limit", "200") - factors, _, err := GetUserFactors(context.Background(), http.DefaultClient, host, key, me.ID, limiter, window, logger) + factors, _, err := GetUserFactors(context.Background(), http.DefaultClient, host, key, me.ID, limiter, logger) if err != nil { t.Fatalf("unexpected error: %v", err) } @@ -175,7 +175,7 @@ func Test(t *testing.T) { query := make(url.Values) query.Set("limit", "200") - users, _, err := GetUserDetails(context.Background(), http.DefaultClient, host, key, login, query, omit, limiter, window, logger) + users, _, err := GetUserDetails(context.Background(), http.DefaultClient, host, key, login, query, omit, limiter, logger) if err != nil { t.Fatalf("unexpected error: %v", err) } @@ -190,7 +190,7 @@ func Test(t *testing.T) { t.Run("all", func(t *testing.T) { query := make(url.Values) query.Set("limit", "200") - users, _, err := GetUserDetails(context.Background(), http.DefaultClient, host, key, "", query, omit, limiter, window, logger) + users, _, err := GetUserDetails(context.Background(), http.DefaultClient, host, key, "", query, omit, limiter, logger) if err != nil { t.Fatalf("unexpected error: %v", err) } @@ -218,7 +218,7 @@ func Test(t *testing.T) { query := make(url.Values) query.Set("limit", "200") query.Add("search", `not (status pr)`) // This cannot ever be true. - _, _, err := GetUserDetails(context.Background(), http.DefaultClient, host, key, "", query, omit, limiter, window, logger) + _, _, err := GetUserDetails(context.Background(), http.DefaultClient, host, key, "", query, omit, limiter, logger) oktaErr := &Error{} if !errors.As(err, &oktaErr) { // Don't test the value of the error since it was @@ -234,7 +234,7 @@ func Test(t *testing.T) { t.Run("device", func(t *testing.T) { query := make(url.Values) query.Set("limit", "200") - devices, _, err := GetDeviceDetails(context.Background(), http.DefaultClient, host, key, "", query, limiter, window, logger) + devices, _, err := GetDeviceDetails(context.Background(), http.DefaultClient, host, key, "", query, limiter, logger) if err != nil { t.Fatalf("unexpected error: %v", err) } @@ -246,7 +246,7 @@ func Test(t *testing.T) { t.Logf("devices: %s", b) } for _, d := range devices { - users, _, err := GetDeviceUsers(context.Background(), http.DefaultClient, host, key, d.ID, query, OmitCredentials, limiter, window, logger) + users, _, err := GetDeviceUsers(context.Background(), http.DefaultClient, host, key, d.ID, query, OmitCredentials, limiter, logger) if err != nil { t.Fatalf("unexpected error: %v", err) } @@ -263,15 +263,15 @@ var localTests = []struct { name string msg string id string - fn func(ctx context.Context, cli *http.Client, host, key, user string, query url.Values, lim RateLimiter, window time.Duration, log *logp.Logger) (any, http.Header, error) + fn func(ctx context.Context, cli *http.Client, host, key, user string, query url.Values, lim *RateLimiter, log *logp.Logger) (any, http.Header, error) mkWant func(string) (any, error) }{ { // Test case constructed from API-returned value with details anonymised. name: "users", msg: `[{"id":"userid","status":"STATUS","created":"2023-05-14T13:37:20.000Z","activated":null,"statusChanged":"2023-05-15T01:50:30.000Z","lastLogin":"2023-05-15T01:59:20.000Z","lastUpdated":"2023-05-15T01:50:32.000Z","passwordChanged":"2023-05-15T01:50:32.000Z","recovery_question":{"question":"Who's a major player in the cowboy scene?","answer":"Annie Oakley"},"type":{"id":"typeid"},"profile":{"firstName":"name","lastName":"surname","mobilePhone":null,"secondEmail":null,"login":"name.surname@example.com","email":"name.surname@example.com"},"credentials":{"password":{"value":"secret"},"emails":[{"value":"name.surname@example.com","status":"VERIFIED","type":"PRIMARY"}],"provider":{"type":"OKTA","name":"OKTA"}},"_links":{"self":{"href":"https://localhost/api/v1/users/userid"}}}]`, - fn: func(ctx context.Context, cli *http.Client, host, key, user string, query url.Values, lim RateLimiter, window time.Duration, log *logp.Logger) (any, http.Header, error) { - return GetUserDetails(context.Background(), cli, host, key, user, query, OmitNone, lim, window, log) + fn: func(ctx context.Context, cli *http.Client, host, key, user string, query url.Values, lim *RateLimiter, log *logp.Logger) (any, http.Header, error) { + return GetUserDetails(context.Background(), cli, host, key, user, query, OmitNone, lim, log) }, mkWant: mkWant[User], }, @@ -279,8 +279,8 @@ var localTests = []struct { // Test case from https://developer.okta.com/docs/api/openapi/okta-management/management/tag/Device/#tag/Device/operation/listDevices name: "devices", msg: `[{"id":"devid","status":"CREATED","created":"2019-10-02T18:03:07.000Z","lastUpdated":"2019-10-02T18:03:07.000Z","profile":{"displayName":"Example Device name 1","platform":"WINDOWS","serialNumber":"XXDDRFCFRGF3M8MD6D","sid":"S-1-11-111","registered":true,"secureHardwarePresent":false,"diskEncryptionType":"ALL_INTERNAL_VOLUMES"},"resourceType":"UDDevice","resourceDisplayName":{"value":"Example Device name 1","sensitive":false},"resourceAlternateId":null,"resourceId":"guo4a5u7YAHhjXrMK0g4","_links":{"activate":{"href":"https://{yourOktaDomain}/api/v1/devices/guo4a5u7YAHhjXrMK0g4/lifecycle/activate","hints":{"allow":["POST"]}},"self":{"href":"https://{yourOktaDomain}/api/v1/devices/guo4a5u7YAHhjXrMK0g4","hints":{"allow":["GET","PATCH","PUT"]}},"users":{"href":"https://{yourOktaDomain}/api/v1/devices/guo4a5u7YAHhjXrMK0g4/users","hints":{"allow":["GET"]}}}},{"id":"guo4a5u7YAHhjXrMK0g5","status":"ACTIVE","created":"2023-06-21T23:24:02.000Z","lastUpdated":"2023-06-21T23:24:02.000Z","profile":{"displayName":"Example Device name 2","platform":"ANDROID","manufacturer":"Google","model":"Pixel 6","osVersion":"13:2023-05-05","registered":true,"secureHardwarePresent":true,"diskEncryptionType":"USER"},"resourceType":"UDDevice","resourceDisplayName":{"value":"Example Device name 2","sensitive":false},"resourceAlternateId":null,"resourceId":"guo4a5u7YAHhjXrMK0g5","_links":{"activate":{"href":"https://{yourOktaDomain}/api/v1/devices/guo4a5u7YAHhjXrMK0g5/lifecycle/activate","hints":{"allow":["POST"]}},"self":{"href":"https://{yourOktaDomain}/api/v1/devices/guo4a5u7YAHhjXrMK0g5","hints":{"allow":["GET","PATCH","PUT"]}},"users":{"href":"https://{yourOktaDomain}/api/v1/devices/guo4a5u7YAHhjXrMK0g5/users","hints":{"allow":["GET"]}}}}]`, - fn: func(ctx context.Context, cli *http.Client, host, key, device string, query url.Values, lim RateLimiter, window time.Duration, log *logp.Logger) (any, http.Header, error) { - return GetDeviceDetails(context.Background(), cli, host, key, device, query, lim, window, log) + fn: func(ctx context.Context, cli *http.Client, host, key, device string, query url.Values, lim *RateLimiter, log *logp.Logger) (any, http.Header, error) { + return GetDeviceDetails(context.Background(), cli, host, key, device, query, lim, log) }, mkWant: mkWant[Device], }, @@ -289,8 +289,8 @@ var localTests = []struct { name: "devices_users", msg: `[{"created":"2023-08-07T21:48:27.000Z","managementStatus":"NOT_MANAGED","user":{"id":"userid","status":"STATUS","created":"2023-05-14T13:37:20.000Z","activated":null,"statusChanged":"2023-05-15T01:50:30.000Z","lastLogin":"2023-05-15T01:59:20.000Z","lastUpdated":"2023-05-15T01:50:32.000Z","passwordChanged":"2023-05-15T01:50:32.000Z","type":{"id":"typeid"},"profile":{"firstName":"name","lastName":"surname","mobilePhone":null,"secondEmail":null,"login":"name.surname@example.com","email":"name.surname@example.com"},"credentials":{"password":{"value":"secret"},"recovery_question":{"question":"Who's a major player in the cowboy scene?","answer":"Annie Oakley"},"emails":[{"value":"name.surname@example.com","status":"VERIFIED","type":"PRIMARY"}],"provider":{"type":"OKTA","name":"OKTA"}},"_links":{"self":{"href":"https://localhost/api/v1/users/userid"}}}}]`, id: "devid", - fn: func(ctx context.Context, cli *http.Client, host, key, device string, query url.Values, lim RateLimiter, window time.Duration, log *logp.Logger) (any, http.Header, error) { - return GetDeviceUsers(context.Background(), cli, host, key, device, query, OmitNone, lim, window, log) + fn: func(ctx context.Context, cli *http.Client, host, key, device string, query url.Values, lim *RateLimiter, log *logp.Logger) (any, http.Header, error) { + return GetDeviceUsers(context.Background(), cli, host, key, device, query, OmitNone, lim, log) }, mkWant: mkWant[devUser], }, @@ -315,12 +315,12 @@ func TestLocal(t *testing.T) { for _, test := range localTests { t.Run(test.name, func(t *testing.T) { - limiter := NewRateLimiter() - // There are a variety of windows, the most conservative is one minute. // The rate limit will be adjusted on the second call to the API if // window is actually used to rate limit calculations. const window = time.Minute + var fixedLimit *int = nil + limiter := NewRateLimiter(window, fixedLimit) const key = "token" want, err := test.mkWant(test.msg) @@ -366,7 +366,7 @@ func TestLocal(t *testing.T) { query := make(url.Values) query.Set("limit", "200") - got, h, err := test.fn(context.Background(), ts.Client(), host, key, test.id, query, limiter, window, logger) + got, h, err := test.fn(context.Background(), ts.Client(), host, key, test.id, query, limiter, logger) if err != nil { t.Fatalf("unexpected error from Get_Details: %v", err) } @@ -375,15 +375,15 @@ func TestLocal(t *testing.T) { t.Errorf("unexpected result:\n- want\n+ got\n%s", cmp.Diff(want, got)) } - if len(limiter) != 1 { - t.Errorf("unexpected number endpoints track by rate limiter: %d", len(limiter)) + if len(limiter.byEndpoint) != 1 { + t.Errorf("unexpected number endpoints track by rate limiter: %d", len(limiter.byEndpoint)) } // retrieve the rate.Limiter parameters for the one endpoint var limit rate.Limit var burst int - for _, l := range limiter { - limit = l.Limit() - burst = l.Burst() + for _, e := range limiter.byEndpoint { + limit = e.limiter.Limit() + burst = e.limiter.Burst() break } diff --git a/x-pack/filebeat/input/entityanalytics/provider/okta/internal/okta/ratelimiter.go b/x-pack/filebeat/input/entityanalytics/provider/okta/internal/okta/ratelimiter.go index 1b58e01328c6..2dfd8ae923bc 100644 --- a/x-pack/filebeat/input/entityanalytics/provider/okta/internal/okta/ratelimiter.go +++ b/x-pack/filebeat/input/entityanalytics/provider/okta/internal/okta/ratelimiter.go @@ -16,33 +16,90 @@ import ( "github.com/elastic/elastic-agent-libs/logp" ) -type RateLimiter map[string]*rate.Limiter +// RateLimiter holds rate limiting information for an API. +// +// Each API endpoint has its own rate limit, which can be dynamically updated +// using response headers. If a fixed limit is set, it takes precedence over any +// information from response headers. +type RateLimiter struct { + window time.Duration + fixedLimit *int + byEndpoint map[string]endpointRateLimiter +} -func NewRateLimiter() RateLimiter { - r := make(RateLimiter) - return r +// endpointRateLimiter represents rate limiting information for a single API endpoint. +type endpointRateLimiter struct { + limiter *rate.Limiter + ready chan struct{} } -func (r RateLimiter) limiter(path string) *rate.Limiter { - if existing, ok := r[path]; ok { +// maxWait defines the maximum wait duration allowed for rate limiting. +// Longer waits are considered errors. +const maxWait = 30 * time.Minute + +// NewRateLimiter constructs a new RateLimiter. +// +// Parameters: +// - `window`: The time between API limit resets. Used for setting an initial +// target rate. +// - `fixedLimit`: A fixed number of requests to allow in each `window`, +// overriding the guidance in API responses. +// +// Returns: +// - A pointer to a new RateLimiter instance. +func NewRateLimiter(window time.Duration, fixedLimit *int) *RateLimiter { + endpoints := make(map[string]endpointRateLimiter) + r := RateLimiter{ + window: window, + fixedLimit: fixedLimit, + byEndpoint: endpoints, + } + r.fixedLimit = fixedLimit + return &r +} + +var immediatelyReady = make(chan struct{}) + +func init() { close(immediatelyReady) } + +func (r RateLimiter) endpoint(path string) endpointRateLimiter { + if existing, ok := r.byEndpoint[path]; ok { return existing } - initial := rate.NewLimiter(1, 1) // Allow a single fetch operation to obtain limits from the API - r[path] = initial - return initial + limit := rate.Limit(1) + if r.fixedLimit != nil { + limit = rate.Limit(float64(*r.fixedLimit) / r.window.Seconds()) + } + limiter := rate.NewLimiter(limit, 1) // Allow a single fetch operation to obtain limits from the API + newEndpointRateLimiter := endpointRateLimiter{ + limiter: limiter, + ready: immediatelyReady, + } + r.byEndpoint[path] = newEndpointRateLimiter + return newEndpointRateLimiter } func (r RateLimiter) Wait(ctx context.Context, endpoint string, url *url.URL, log *logp.Logger) (err error) { - limiter := r.limiter(endpoint) - log.Debugw("rate limit", "limit", limiter.Limit(), "burst", limiter.Burst(), "url", url.String()) - return limiter.Wait(ctx) + e := r.endpoint(endpoint) + log.Debugw("rate limit", "limit", e.limiter.Limit(), "burst", e.limiter.Burst(), "url", url.String()) + ctxWithDeadline, cancel := context.WithDeadline(ctx, time.Now().Add(maxWait)) + defer cancel() + select { + case <-e.ready: + case <-ctxWithDeadline.Done(): + return ctxWithDeadline.Err() + } + return e.limiter.Wait(ctxWithDeadline) } // Update implements the Okta rate limit policy translation. // // See https://developer.okta.com/docs/reference/rl-best-practices/ for details. -func (r RateLimiter) Update(endpoint string, h http.Header, window time.Duration, log *logp.Logger) error { - limiter := r.limiter(endpoint) +func (r RateLimiter) Update(endpoint string, h http.Header, log *logp.Logger) error { + if r.fixedLimit != nil { + return nil + } + e := r.endpoint(endpoint) limit := h.Get("X-Rate-Limit-Limit") remaining := h.Get("X-Rate-Limit-Remaining") reset := h.Get("X-Rate-Limit-Reset") @@ -78,20 +135,33 @@ func (r RateLimiter) Update(endpoint string, h http.Header, window time.Duration if rateLimit <= 0 { // Reset limiter to block requests until reset limiter := rate.NewLimiter(0, 0) - r[endpoint] = limiter + ready := make(chan struct{}) + newEndpointRateLimiter := endpointRateLimiter{ + limiter: limiter, + ready: ready, + } + r.byEndpoint[endpoint] = newEndpointRateLimiter + + resetTimeUTC := resetTime.UTC() + log.Debugw("rate limit block until reset", "reset_time", resetTimeUTC) // next gives us a sane next window estimate, but the // estimate will be overwritten when we make the next // permissible API request. - next := rate.Limit(lim / window.Seconds()) - waitUntil := resetTime.UTC() - limiter.SetLimitAt(waitUntil, next) - limiter.SetBurstAt(waitUntil, burst) - log.Debugw("rate limit reset", "reset_time", waitUntil, "next_rate", next, "next_burst", burst) + next := rate.Limit(lim / r.window.Seconds()) + waitFor := time.Until(resetTimeUTC) + + time.AfterFunc(waitFor, func() { + limiter.SetLimit(next) + limiter.SetBurst(burst) + close(ready) + log.Debugw("rate limit reset", "reset_time", resetTimeUTC, "reset_rate", next, "reset_burst", burst) + }) + return nil } - limiter.SetLimit(rateLimit) - limiter.SetBurst(burst) + e.limiter.SetLimit(rateLimit) + e.limiter.SetBurst(burst) log.Debugw("rate limit adjust", "set_rate", rateLimit, "set_burst", burst) return nil } diff --git a/x-pack/filebeat/input/entityanalytics/provider/okta/internal/okta/ratelimiter_test.go b/x-pack/filebeat/input/entityanalytics/provider/okta/internal/okta/ratelimiter_test.go index 1492e55c8a67..cc8a832bee2e 100644 --- a/x-pack/filebeat/input/entityanalytics/provider/okta/internal/okta/ratelimiter_test.go +++ b/x-pack/filebeat/input/entityanalytics/provider/okta/internal/okta/ratelimiter_test.go @@ -5,7 +5,9 @@ package okta import ( + "context" "net/http" + "net/url" "strconv" "testing" "time" @@ -17,68 +19,151 @@ func TestRateLimiter(t *testing.T) { logp.TestingSetup() t.Run("separation by endpoint", func(t *testing.T) { - r := NewRateLimiter() - limiter1 := r.limiter("/foo") - limiter2 := r.limiter("/bar") + const window = time.Minute + var fixedLimit *int = nil + r := NewRateLimiter(window, fixedLimit) + e1 := r.endpoint("/foo") + e2 := r.endpoint("/bar") - limiter1.SetBurst(1000) + e1.limiter.SetBurst(1000) - if limiter2.Burst() == 1000 { + if e2.limiter.Burst() == 1000 { t.Errorf("changes to one endpoint's limits affected another") } }) t.Run("Update stops requests when none are remaining", func(t *testing.T) { - r := NewRateLimiter() - + const window = time.Minute + var fixedLimit *int = nil + r := NewRateLimiter(window, fixedLimit) const endpoint = "/foo" - limiter := r.limiter(endpoint) + url, err := url.Parse(endpoint) + if err != nil { + t.Errorf("unexpected error from url.Parse(): %v", err) + } + ctx := context.Background() + log := logp.L() + e := r.endpoint(endpoint) - if !limiter.Allow() { + if !e.limiter.Allow() { t.Errorf("doesn't allow an initial request") } + // update to none remaining, reset soon now := time.Now().Unix() - reset := now + 30 - + resetSoon := now + 30 headers := http.Header{ "X-Rate-Limit-Limit": []string{"60"}, "X-Rate-Limit-Remaining": []string{"0"}, - "X-Rate-Limit-Reset": []string{strconv.FormatInt(reset, 10)}, + "X-Rate-Limit-Reset": []string{strconv.FormatInt(resetSoon, 10)}, } - window := time.Minute - - err := r.Update(endpoint, headers, window, logp.L()) + err = r.Update(endpoint, headers, logp.L()) if err != nil { t.Errorf("unexpected error from Update(): %v", err) } - limiter = r.limiter(endpoint) + e = r.endpoint(endpoint) - if limiter.Allow() { + if e.limiter.Allow() { t.Errorf("allowed a request when none are remaining") } - - if limiter.AllowN(time.Unix(reset-1, 999999999), 1) { + if e.limiter.AllowN(time.Unix(resetSoon-1, 999999999), 1) { t.Errorf("allowed a request before reset, when none are remaining") } - if !limiter.AllowN(time.Unix(reset+1, 0), 1) { - t.Errorf("doesn't allow requests to resume after reset") + // update to none remaining, reset now + headers = http.Header{ + "X-Rate-Limit-Limit": []string{"60"}, + "X-Rate-Limit-Remaining": []string{"0"}, + "X-Rate-Limit-Reset": []string{strconv.FormatInt(now, 10)}, + } + err = r.Update(endpoint, headers, logp.L()) + if err != nil { + t.Errorf("unexpected error from Update(): %v", err) + } + e = r.endpoint(endpoint) + + start := time.Now() + r.Wait(ctx, endpoint, url, log) + wait := time.Since(start) + + if wait > 1010*time.Millisecond { + t.Errorf("doesn't allow requests to resume after reset. had to wait %s", wait) + } + if e.limiter.Limit() != 1.0 { + t.Errorf("unexpected rate following reset (not 60 requests / 60 seconds): %f", e.limiter.Limit()) + } + if e.limiter.Burst() != 1 { + t.Errorf("unexpected burst following reset (not 1): %d", e.limiter.Burst()) + } + + e.limiter.SetBurst(100) // increase bucket size to check token accumulation + tokens := e.limiter.TokensAt(time.Unix(0, time.Now().Add(30*time.Second).UnixNano())) + target := 30.0 + buffer := 0.01 + + if tokens < target-buffer || target+buffer < tokens { + t.Errorf("tokens don't accumulate at the expected rate over 30s: %f", tokens) + } + }) + + t.Run("Very long waits are considered errors", func(t *testing.T) { + const window = time.Minute + var fixedLimit *int = nil + r := NewRateLimiter(window, fixedLimit) + + const endpoint = "/foo" + + url, err := url.Parse(endpoint) + if err != nil { + t.Errorf("unexpected error from url.Parse(): %v", err) } + reset := time.Now().Add(31 * time.Minute).Unix() + headers := http.Header{ + "X-Rate-Limit-Limit": []string{"60"}, + "X-Rate-Limit-Remaining": []string{"1"}, + "X-Rate-Limit-Reset": []string{strconv.FormatInt(reset, 10)}, + } + log := logp.L() + ctx := context.Background() + + r.Wait(ctx, endpoint, url, log) // consume the initial request + r.Update(endpoint, headers, log) // update to a slow rate - if limiter.Limit() != 1.0 { - t.Errorf("unexpected rate following reset (not 60 requests / 60 seconds): %f", limiter.Limit()) + err = r.Wait(ctx, endpoint, url, log) + + const expectedErr = "rate: Wait(n=1) would exceed context deadline" + if err == nil { + t.Errorf("expected error message %q, but got no error", expectedErr) + } else if err.Error() != expectedErr { + t.Errorf("expected error message %q, but got %q", expectedErr, err.Error()) } + }) - if limiter.Burst() != 1 { - t.Errorf("unexpected burst following reset (not 1): %d", limiter.Burst()) + t.Run("A fixed limit overrides response information", func(t *testing.T) { + const window = time.Minute + var fixedLimit int = 120 + r := NewRateLimiter(window, &fixedLimit) + const endpoint = "/foo" + e := r.endpoint(endpoint) + + if e.limiter.Limit() != 120/60 { + t.Errorf("unexpected rate (for fixed 120 reqs / 60 secs): %f", e.limiter.Limit()) } - limiter.SetBurstAt(time.Unix(reset, 0), 100) // increase bucket size to check token accumulation - tokens := limiter.TokensAt(time.Unix(reset+30, 0)) - if tokens < 29.5 || tokens > 30.0 { - t.Errorf("tokens don't accumulate at the expected rate. tokens 30s after reset: %f", tokens) + // update to 15 requests remaining, reset in 30s + headers := http.Header{ + "X-Rate-Limit-Limit": []string{"60"}, + "X-Rate-Limit-Remaining": []string{"15"}, + "X-Rate-Limit-Reset": []string{strconv.FormatInt(time.Now().Unix()+30, 10)}, } + err := r.Update(endpoint, headers, logp.L()) + if err != nil { + t.Errorf("unexpected error from Update(): %v", err) + } + e = r.endpoint(endpoint) + if e.limiter.Limit() != 120/60 { + t.Errorf("unexpected rate following Update() (for fixed 120 reqs / 60 secs): %f", e.limiter.Limit()) + } }) } diff --git a/x-pack/filebeat/input/entityanalytics/provider/okta/okta.go b/x-pack/filebeat/input/entityanalytics/provider/okta/okta.go index 30103d3ccdb7..0e33e93cc9b9 100644 --- a/x-pack/filebeat/input/entityanalytics/provider/okta/okta.go +++ b/x-pack/filebeat/input/entityanalytics/provider/okta/okta.go @@ -59,7 +59,7 @@ type oktaInput struct { cfg conf client *http.Client - lim okta.RateLimiter + lim *okta.RateLimiter metrics *inputMetrics logger *logp.Logger @@ -110,7 +110,7 @@ func (p *oktaInput) Run(inputCtx v2.Context, store *kvstore.Store, client beat.C updateTimer := time.NewTimer(updateWaitTime) // Allow a single fetch operation to obtain limits from the API. - p.lim = okta.NewRateLimiter() + p.lim = okta.NewRateLimiter(p.cfg.LimitWindow, p.cfg.LimitFixed) if p.cfg.Tracer != nil { id := sanitizeFileName(inputCtx.IDWithoutName) @@ -451,7 +451,7 @@ func (p *oktaInput) doFetchUsers(ctx context.Context, state *stateStore, fullSyn lastUpdated time.Time ) for { - batch, h, err := okta.GetUserDetails(ctx, p.client, p.cfg.OktaDomain, p.cfg.OktaToken, "", query, omit, p.lim, p.cfg.LimitWindow, p.logger) + batch, h, err := okta.GetUserDetails(ctx, p.client, p.cfg.OktaDomain, p.cfg.OktaToken, "", query, omit, p.lim, p.logger) if err != nil { p.logger.Debugf("received %d users from API", len(users)) return nil, err @@ -512,7 +512,7 @@ func (p *oktaInput) addUserMetadata(ctx context.Context, u okta.User, state *sta return su } if slices.Contains(p.cfg.EnrichWith, "groups") { - groups, _, err := okta.GetUserGroupDetails(ctx, p.client, p.cfg.OktaDomain, p.cfg.OktaToken, u.ID, p.lim, p.cfg.LimitWindow, p.logger) + groups, _, err := okta.GetUserGroupDetails(ctx, p.client, p.cfg.OktaDomain, p.cfg.OktaToken, u.ID, p.lim, p.logger) if err != nil { p.logger.Warnf("failed to get user group membership for %s: %v", u.ID, err) } else { @@ -520,7 +520,7 @@ func (p *oktaInput) addUserMetadata(ctx context.Context, u okta.User, state *sta } } if slices.Contains(p.cfg.EnrichWith, "factors") { - factors, _, err := okta.GetUserFactors(ctx, p.client, p.cfg.OktaDomain, p.cfg.OktaToken, u.ID, p.lim, p.cfg.LimitWindow, p.logger) + factors, _, err := okta.GetUserFactors(ctx, p.client, p.cfg.OktaDomain, p.cfg.OktaToken, u.ID, p.lim, p.logger) if err != nil { p.logger.Warnf("failed to get user factors for %s: %v", u.ID, err) } else { @@ -528,7 +528,7 @@ func (p *oktaInput) addUserMetadata(ctx context.Context, u okta.User, state *sta } } if slices.Contains(p.cfg.EnrichWith, "roles") { - roles, _, err := okta.GetUserRoles(ctx, p.client, p.cfg.OktaDomain, p.cfg.OktaToken, u.ID, p.lim, p.cfg.LimitWindow, p.logger) + roles, _, err := okta.GetUserRoles(ctx, p.client, p.cfg.OktaDomain, p.cfg.OktaToken, u.ID, p.lim, p.logger) if err != nil { p.logger.Warnf("failed to get user roles for %s: %v", u.ID, err) } else { @@ -580,7 +580,7 @@ func (p *oktaInput) doFetchDevices(ctx context.Context, state *stateStore, fullS lastUpdated time.Time ) for { - batch, h, err := okta.GetDeviceDetails(ctx, p.client, p.cfg.OktaDomain, p.cfg.OktaToken, "", deviceQuery, p.lim, p.cfg.LimitWindow, p.logger) + batch, h, err := okta.GetDeviceDetails(ctx, p.client, p.cfg.OktaDomain, p.cfg.OktaToken, "", deviceQuery, p.lim, p.logger) if err != nil { p.logger.Debugf("received %d devices from API", len(devices)) return nil, err @@ -599,7 +599,7 @@ func (p *oktaInput) doFetchDevices(ctx context.Context, state *stateStore, fullS const omit = okta.OmitCredentials | okta.OmitCredentialsLinks | okta.OmitTransitioningToStatus - users, h, err := okta.GetDeviceUsers(ctx, p.client, p.cfg.OktaDomain, p.cfg.OktaToken, d.ID, userQuery, omit, p.lim, p.cfg.LimitWindow, p.logger) + users, h, err := okta.GetDeviceUsers(ctx, p.client, p.cfg.OktaDomain, p.cfg.OktaToken, d.ID, userQuery, omit, p.lim, p.logger) if err != nil { p.logger.Debugf("received %d device users from API", len(users)) return nil, err diff --git a/x-pack/filebeat/input/entityanalytics/provider/okta/okta_test.go b/x-pack/filebeat/input/entityanalytics/provider/okta/okta_test.go index e7e2bffbba24..ea2a710d8c51 100644 --- a/x-pack/filebeat/input/entityanalytics/provider/okta/okta_test.go +++ b/x-pack/filebeat/input/entityanalytics/provider/okta/okta_test.go @@ -176,7 +176,7 @@ func TestOktaDoFetch(t *testing.T) { if err != nil { t.Errorf("failed to parse server URL: %v", err) } - rateLimiter := okta.NewRateLimiter() + rateLimiter := okta.NewRateLimiter(window, nil) a := oktaInput{ cfg: conf{ OktaDomain: u.Host, From 20715c377f734cba5740bb2fc3ae47929ce09315 Mon Sep 17 00:00:00 2001 From: Nassim Kammah Date: Thu, 12 Dec 2024 10:38:27 +0100 Subject: [PATCH 43/48] Remove Nassim from ironbank maintainers list (#41916) * Remove Nassim from ironbank maintainers list The Ironbank sends me notifications of actions to take for the beats* containers, but there is nothing I can action on my side. * Remove Nassim from other manifests --- .../templates/ironbank/auditbeat/hardening_manifest.yaml | 3 --- .../templates/ironbank/filebeat/hardening_manifest.yaml | 3 --- .../templates/ironbank/heartbeat/hardening_manifest.yaml | 3 --- .../templates/ironbank/metricbeat/hardening_manifest.yaml | 3 --- .../templates/ironbank/packetbeat/hardening_manifest.yaml | 3 --- 5 files changed, 15 deletions(-) diff --git a/dev-tools/packaging/templates/ironbank/auditbeat/hardening_manifest.yaml b/dev-tools/packaging/templates/ironbank/auditbeat/hardening_manifest.yaml index ca03186ba65a..ff5c9bb42ed9 100644 --- a/dev-tools/packaging/templates/ironbank/auditbeat/hardening_manifest.yaml +++ b/dev-tools/packaging/templates/ironbank/auditbeat/hardening_manifest.yaml @@ -52,9 +52,6 @@ resources: # List of project maintainers maintainers: - - email: "nassim.kammah@elastic.co" - name: "Nassim Kammah" - username: "nassim.kammah" - email: "julien.lind@elastic.co" name: "Julien lind" username: "julien.lind" diff --git a/dev-tools/packaging/templates/ironbank/filebeat/hardening_manifest.yaml b/dev-tools/packaging/templates/ironbank/filebeat/hardening_manifest.yaml index a178d6f9cf1a..1f89df0d0ce5 100644 --- a/dev-tools/packaging/templates/ironbank/filebeat/hardening_manifest.yaml +++ b/dev-tools/packaging/templates/ironbank/filebeat/hardening_manifest.yaml @@ -52,9 +52,6 @@ resources: # List of project maintainers maintainers: - - email: "nassim.kammah@elastic.co" - name: "Nassim Kammah" - username: "nassim.kammah" - email: "julien.lind@elastic.co" name: "Julien lind" username: "julien.lind" diff --git a/dev-tools/packaging/templates/ironbank/heartbeat/hardening_manifest.yaml b/dev-tools/packaging/templates/ironbank/heartbeat/hardening_manifest.yaml index fda278bd0378..18c4ee47b367 100644 --- a/dev-tools/packaging/templates/ironbank/heartbeat/hardening_manifest.yaml +++ b/dev-tools/packaging/templates/ironbank/heartbeat/hardening_manifest.yaml @@ -52,9 +52,6 @@ resources: # List of project maintainers maintainers: - - email: "nassim.kammah@elastic.co" - name: "Nassim Kammah" - username: "nassim.kammah" - email: "julien.lind@elastic.co" name: "Julien lind" username: "julien.lind" diff --git a/dev-tools/packaging/templates/ironbank/metricbeat/hardening_manifest.yaml b/dev-tools/packaging/templates/ironbank/metricbeat/hardening_manifest.yaml index b6262a06852b..6635eb872770 100644 --- a/dev-tools/packaging/templates/ironbank/metricbeat/hardening_manifest.yaml +++ b/dev-tools/packaging/templates/ironbank/metricbeat/hardening_manifest.yaml @@ -52,9 +52,6 @@ resources: # List of project maintainers maintainers: - - email: "nassim.kammah@elastic.co" - name: "Nassim Kammah" - username: "nassim.kammah" - email: "julien.lind@elastic.co" name: "Julien lind" username: "julien.lind" diff --git a/dev-tools/packaging/templates/ironbank/packetbeat/hardening_manifest.yaml b/dev-tools/packaging/templates/ironbank/packetbeat/hardening_manifest.yaml index 23bb1cfc76a0..d7b97a92f87d 100644 --- a/dev-tools/packaging/templates/ironbank/packetbeat/hardening_manifest.yaml +++ b/dev-tools/packaging/templates/ironbank/packetbeat/hardening_manifest.yaml @@ -52,9 +52,6 @@ resources: # List of project maintainers maintainers: - - email: "nassim.kammah@elastic.co" - name: "Nassim Kammah" - username: "nassim.kammah" - email: "julien.lind@elastic.co" name: "Julien lind" username: "julien.lind" From 560b842a1825334a2b0db6a732c7b8e403771cbc Mon Sep 17 00:00:00 2001 From: Christiano Haesbaert Date: Thu, 12 Dec 2024 12:02:55 +0100 Subject: [PATCH 44/48] auditbeat: Split common tty definitions (#42004) No functional changes, just move tty things to a common place so that the upcoming system/process provider can use it. Last of the PRs to split common code for the new system/process provider (I promise). --- CHANGELOG.next.asciidoc | 1 + auditbeat/helper/tty/tty.go | 76 +++++++++++++++++++ .../processors/sessionmd/processdb/db.go | 69 +++++------------ .../processors/sessionmd/processdb/db_test.go | 9 ++- .../sessionmd/processdb/entry_leader_test.go | 21 ++--- .../processors/sessionmd/procfs/procfs.go | 5 +- .../kerneltracingprovider_linux.go | 50 ++---------- .../processors/sessionmd/types/events.go | 23 +----- 8 files changed, 123 insertions(+), 131 deletions(-) create mode 100644 auditbeat/helper/tty/tty.go diff --git a/CHANGELOG.next.asciidoc b/CHANGELOG.next.asciidoc index 6840ef4ed533..11e20daeacb7 100644 --- a/CHANGELOG.next.asciidoc +++ b/CHANGELOG.next.asciidoc @@ -128,6 +128,7 @@ https://github.com/elastic/beats/compare/v8.8.1\...main[Check the HEAD diff] - auditd: Update syscall names for Linux 6.11. {pull}41558[41558] - hasher: Geneneral improvements and fixes. {pull}41863[41863] - hasher: Add a cached hasher for upcoming backend. {pull}41952[41952] +- Split common tty definitions. {pull}42004[42004] *Filebeat* diff --git a/auditbeat/helper/tty/tty.go b/auditbeat/helper/tty/tty.go new file mode 100644 index 000000000000..509fa6b9aa68 --- /dev/null +++ b/auditbeat/helper/tty/tty.go @@ -0,0 +1,76 @@ +// Licensed to Elasticsearch B.V. under one or more contributor +// license agreements. See the NOTICE file distributed with +// this work for additional information regarding copyright +// ownership. Elasticsearch B.V. licenses this file to you under +// the Apache License, Version 2.0 (the "License"); you may +// not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, +// software distributed under the License is distributed on an +// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +// KIND, either express or implied. See the License for the +// specific language governing permissions and limitations +// under the License. + +package tty + +type TTYType int + +const ( + TTYUnknown TTYType = iota + Pts + TTY + TTYConsole +) + +const ( + ptsMinMajor = 136 + ptsMaxMajor = 143 + ttyMajor = 4 + consoleMaxMinor = 63 + ttyMaxMinor = 255 +) + +type TTYDev struct { + Minor uint32 + Major uint32 + Winsize TTYWinsize + Termios TTYTermios +} + +type TTYWinsize struct { + Rows uint16 + Cols uint16 +} + +type TTYTermios struct { + CIflag uint32 + COflag uint32 + CLflag uint32 + CCflag uint32 +} + +// interactiveFromTTY returns if this is an interactive tty device. +func InteractiveFromTTY(tty TTYDev) bool { + return TTYUnknown != GetTTYType(tty.Major, tty.Minor) +} + +// getTTYType returns the type of a TTY device based on its major and minor numbers. +func GetTTYType(major uint32, minor uint32) TTYType { + if major >= ptsMinMajor && major <= ptsMaxMajor { + return Pts + } + + if ttyMajor == major { + if minor <= consoleMaxMinor { + return TTYConsole + } else if minor > consoleMaxMinor && minor <= ttyMaxMinor { + return TTY + } + } + + return TTYUnknown +} diff --git a/x-pack/auditbeat/processors/sessionmd/processdb/db.go b/x-pack/auditbeat/processors/sessionmd/processdb/db.go index 1f97f7d0fd58..e9e53eb965ac 100644 --- a/x-pack/auditbeat/processors/sessionmd/processdb/db.go +++ b/x-pack/auditbeat/processors/sessionmd/processdb/db.go @@ -20,6 +20,7 @@ import ( "sync" "time" + "github.com/elastic/beats/v7/auditbeat/helper/tty" "github.com/elastic/beats/v7/libbeat/common/capabilities" "github.com/elastic/beats/v7/x-pack/auditbeat/processors/sessionmd/procfs" "github.com/elastic/beats/v7/x-pack/auditbeat/processors/sessionmd/timeutils" @@ -27,15 +28,6 @@ import ( "github.com/elastic/elastic-agent-libs/logp" ) -type TTYType int - -const ( - TTYUnknown TTYType = iota - Pts - TTY - TTYConsole -) - type EntryType string const ( @@ -67,18 +59,13 @@ var filteredExecutables = [...]string{ } const ( - ptsMinMajor = 136 - ptsMaxMajor = 143 - ttyMajor = 4 - consoleMaxMinor = 63 - ttyMaxMinor = 255 - retryCount = 2 + retryCount = 2 ) type Process struct { PIDs types.PIDInfo Creds types.CredInfo - CTTY types.TTYDev + CTTY tty.TTYDev Argv []string Cwd string Env map[string]string @@ -142,8 +129,8 @@ func credInfoFromProto(p types.CredInfo) types.CredInfo { } } -func ttyTermiosFromProto(p types.TTYTermios) types.TTYTermios { - return types.TTYTermios{ +func ttyTermiosFromProto(p tty.TTYTermios) tty.TTYTermios { + return tty.TTYTermios{ CIflag: p.CIflag, COflag: p.COflag, CLflag: p.CLflag, @@ -151,15 +138,15 @@ func ttyTermiosFromProto(p types.TTYTermios) types.TTYTermios { } } -func ttyWinsizeFromProto(p types.TTYWinsize) types.TTYWinsize { - return types.TTYWinsize{ +func ttyWinsizeFromProto(p tty.TTYWinsize) tty.TTYWinsize { + return tty.TTYWinsize{ Rows: p.Rows, Cols: p.Cols, } } -func ttyDevFromProto(p types.TTYDev) types.TTYDev { - return types.TTYDev{ +func ttyDevFromProto(p tty.TTYDev) tty.TTYDev { + return tty.TTYDev{ Major: p.Major, Minor: p.Minor, Winsize: ttyWinsizeFromProto(p.Winsize), @@ -319,15 +306,15 @@ func (db *DB) evaluateEntryLeader(p Process) *uint32 { // could be an entry leader if p.PIDs.Tgid == p.PIDs.Sid { - ttyType := getTTYType(p.CTTY.Major, p.CTTY.Minor) + ttyType := tty.GetTTYType(p.CTTY.Major, p.CTTY.Minor) procBasename := basename(p.Filename) switch { - case ttyType == TTY: + case ttyType == tty.TTY: db.createEntryLeader(pid, Terminal) db.logger.Debugf("entry_eval %d: entry type is terminal", p.PIDs.Tgid) return &pid - case ttyType == TTYConsole && procBasename == "login": + case ttyType == tty.TTYConsole && procBasename == "login": db.createEntryLeader(pid, EntryConsole) db.logger.Debugf("entry_eval %d: entry type is console", p.PIDs.Tgid) return &pid @@ -338,7 +325,7 @@ func (db *DB) evaluateEntryLeader(p Process) *uint32 { case !isFilteredExecutable(procBasename): if parent, ok := db.processes[p.PIDs.Ppid]; ok { parentBasename := basename(parent.Filename) - if ttyType == Pts && parentBasename == "ssm-session-worker" { + if ttyType == tty.Pts && parentBasename == "ssm-session-worker" { db.createEntryLeader(pid, Ssm) db.logger.Debugf("entry_eval %d: entry type is ssm", p.PIDs.Tgid) return &pid @@ -433,13 +420,9 @@ func (db *DB) InsertExit(exit types.ProcessExitEvent) { }) } -func interactiveFromTTY(tty types.TTYDev) bool { - return TTYUnknown != getTTYType(tty.Major, tty.Minor) -} - func fullProcessFromDBProcess(p Process) types.Process { reducedPrecisionStartTime := timeutils.ReduceTimestampPrecision(p.PIDs.StartTimeNS) - interactive := interactiveFromTTY(p.CTTY) + interactive := tty.InteractiveFromTTY(p.CTTY) ret := types.Process{ PID: p.PIDs.Tgid, @@ -475,7 +458,7 @@ func fullProcessFromDBProcess(p Process) types.Process { func fillParent(process *types.Process, parent Process) { reducedPrecisionStartTime := timeutils.ReduceTimestampPrecision(parent.PIDs.StartTimeNS) - interactive := interactiveFromTTY(parent.CTTY) + interactive := tty.InteractiveFromTTY(parent.CTTY) euid := parent.Creds.Euid egid := parent.Creds.Egid process.Parent.PID = parent.PIDs.Tgid @@ -500,7 +483,7 @@ func fillParent(process *types.Process, parent Process) { func fillGroupLeader(process *types.Process, groupLeader Process) { reducedPrecisionStartTime := timeutils.ReduceTimestampPrecision(groupLeader.PIDs.StartTimeNS) - interactive := interactiveFromTTY(groupLeader.CTTY) + interactive := tty.InteractiveFromTTY(groupLeader.CTTY) euid := groupLeader.Creds.Euid egid := groupLeader.Creds.Egid process.GroupLeader.PID = groupLeader.PIDs.Tgid @@ -525,7 +508,7 @@ func fillGroupLeader(process *types.Process, groupLeader Process) { func fillSessionLeader(process *types.Process, sessionLeader Process) { reducedPrecisionStartTime := timeutils.ReduceTimestampPrecision(sessionLeader.PIDs.StartTimeNS) - interactive := interactiveFromTTY(sessionLeader.CTTY) + interactive := tty.InteractiveFromTTY(sessionLeader.CTTY) euid := sessionLeader.Creds.Euid egid := sessionLeader.Creds.Egid process.SessionLeader.PID = sessionLeader.PIDs.Tgid @@ -550,7 +533,7 @@ func fillSessionLeader(process *types.Process, sessionLeader Process) { func fillEntryLeader(process *types.Process, entryType EntryType, entryLeader Process) { reducedPrecisionStartTime := timeutils.ReduceTimestampPrecision(entryLeader.PIDs.StartTimeNS) - interactive := interactiveFromTTY(entryLeader.CTTY) + interactive := tty.InteractiveFromTTY(entryLeader.CTTY) euid := entryLeader.Creds.Euid egid := entryLeader.Creds.Egid process.EntryLeader.PID = entryLeader.PIDs.Tgid @@ -743,22 +726,6 @@ func isFilteredExecutable(executable string) bool { return stringStartsWithEntryInList(executable, filteredExecutables[:]) } -func getTTYType(major uint32, minor uint32) TTYType { - if major >= ptsMinMajor && major <= ptsMaxMajor { - return Pts - } - - if ttyMajor == major { - if minor <= consoleMaxMinor { - return TTYConsole - } else if minor > consoleMaxMinor && minor <= ttyMaxMinor { - return TTY - } - } - - return TTYUnknown -} - func (db *DB) Close() { close(db.stopChan) } diff --git a/x-pack/auditbeat/processors/sessionmd/processdb/db_test.go b/x-pack/auditbeat/processors/sessionmd/processdb/db_test.go index 086c694f51fa..5cd1eed1ffcb 100644 --- a/x-pack/auditbeat/processors/sessionmd/processdb/db_test.go +++ b/x-pack/auditbeat/processors/sessionmd/processdb/db_test.go @@ -11,14 +11,15 @@ import ( "github.com/stretchr/testify/require" + "github.com/elastic/beats/v7/auditbeat/helper/tty" "github.com/elastic/elastic-agent-libs/logp" ) var logger = logp.NewLogger("processdb") func TestGetTTYType(t *testing.T) { - require.Equal(t, TTYConsole, getTTYType(4, 0)) - require.Equal(t, Pts, getTTYType(136, 0)) - require.Equal(t, TTY, getTTYType(4, 64)) - require.Equal(t, TTYUnknown, getTTYType(1000, 1000)) + require.Equal(t, tty.TTYConsole, tty.GetTTYType(4, 0)) + require.Equal(t, tty.Pts, tty.GetTTYType(136, 0)) + require.Equal(t, tty.TTY, tty.GetTTYType(4, 64)) + require.Equal(t, tty.TTYUnknown, tty.GetTTYType(1000, 1000)) } diff --git a/x-pack/auditbeat/processors/sessionmd/processdb/entry_leader_test.go b/x-pack/auditbeat/processors/sessionmd/processdb/entry_leader_test.go index fa0bc6e17993..a3315d61b4c4 100644 --- a/x-pack/auditbeat/processors/sessionmd/processdb/entry_leader_test.go +++ b/x-pack/auditbeat/processors/sessionmd/processdb/entry_leader_test.go @@ -12,6 +12,7 @@ import ( "github.com/stretchr/testify/require" + "github.com/elastic/beats/v7/auditbeat/helper/tty" "github.com/elastic/beats/v7/x-pack/auditbeat/processors/sessionmd/procfs" "github.com/elastic/beats/v7/x-pack/auditbeat/processors/sessionmd/types" ) @@ -201,7 +202,7 @@ func TestSingleProcessSessionLeaderEntryTypeTerminal(t *testing.T) { Tgid: pid, Sid: pid, }, - CTTY: types.TTYDev{ + CTTY: tty.TTYDev{ Major: 4, Minor: 64, }, @@ -225,7 +226,7 @@ func TestSingleProcessSessionLeaderLoginProcess(t *testing.T) { Tgid: pid, Sid: pid, }, - CTTY: types.TTYDev{ + CTTY: tty.TTYDev{ Major: 4, Minor: 62, }, @@ -255,7 +256,7 @@ func TestSingleProcessSessionLeaderChildOfInit(t *testing.T) { Sid: pid, Ppid: 1, }, - CTTY: types.TTYDev{ + CTTY: tty.TTYDev{ Major: 136, Minor: 62, }, @@ -294,7 +295,7 @@ func TestSingleProcessSessionLeaderChildOfSsmSessionWorker(t *testing.T) { Sid: bashPID, Ppid: ssmPID, }, - CTTY: types.TTYDev{ + CTTY: tty.TTYDev{ Major: 136, Minor: 62, }, @@ -329,7 +330,7 @@ func TestSingleProcessSessionLeaderChildOfSshd(t *testing.T) { Sid: bashPID, Ppid: sshdPID, }, - CTTY: types.TTYDev{ + CTTY: tty.TTYDev{ Major: 136, Minor: 62, }, @@ -364,7 +365,7 @@ func TestSingleProcessSessionLeaderChildOfContainerdShim(t *testing.T) { Sid: bashPID, Ppid: containerdShimPID, }, - CTTY: types.TTYDev{ + CTTY: tty.TTYDev{ Major: 136, Minor: 62, }, @@ -400,7 +401,7 @@ func TestSingleProcessSessionLeaderChildOfRunc(t *testing.T) { Sid: bashPID, Ppid: runcPID, }, - CTTY: types.TTYDev{ + CTTY: tty.TTYDev{ Major: 136, Minor: 62, }, @@ -428,7 +429,7 @@ func TestSingleProcessEmptyProcess(t *testing.T) { Tgid: pid, Sid: pid, }, - CTTY: types.TTYDev{ + CTTY: tty.TTYDev{ Major: 136, Minor: 62, }, @@ -471,7 +472,7 @@ func TestSingleProcessOverwriteOldEntryLeader(t *testing.T) { Sid: ssmPID, Ppid: ssmPID, }, - CTTY: types.TTYDev{ + CTTY: tty.TTYDev{ Major: 136, Minor: 62, }, @@ -492,7 +493,7 @@ func TestSingleProcessOverwriteOldEntryLeader(t *testing.T) { Sid: bashPID, Ppid: ssmPID, }, - CTTY: types.TTYDev{ + CTTY: tty.TTYDev{ Major: 136, Minor: 62, }, diff --git a/x-pack/auditbeat/processors/sessionmd/procfs/procfs.go b/x-pack/auditbeat/processors/sessionmd/procfs/procfs.go index 992e24858363..2d5d26bc3883 100644 --- a/x-pack/auditbeat/processors/sessionmd/procfs/procfs.go +++ b/x-pack/auditbeat/processors/sessionmd/procfs/procfs.go @@ -13,6 +13,7 @@ import ( "github.com/prometheus/procfs" "golang.org/x/sys/unix" + "github.com/elastic/beats/v7/auditbeat/helper/tty" "github.com/elastic/beats/v7/x-pack/auditbeat/processors/sessionmd/timeutils" "github.com/elastic/beats/v7/x-pack/auditbeat/processors/sessionmd/types" "github.com/elastic/elastic-agent-libs/logp" @@ -47,7 +48,7 @@ type Stat procfs.ProcStat type ProcessInfo struct { PIDs types.PIDInfo Creds types.CredInfo - CTTY types.TTYDev + CTTY tty.TTYDev Argv []string Cwd string Env map[string]string @@ -165,7 +166,7 @@ func (r ProcfsReader) getProcessInfo(proc procfs.Proc) (ProcessInfo, error) { Sid: uint32(stat.Session), }, Creds: creds, - CTTY: types.TTYDev{ + CTTY: tty.TTYDev{ Major: MajorTTY(uint32(stat.TTY)), Minor: MinorTTY(uint32(stat.TTY)), }, diff --git a/x-pack/auditbeat/processors/sessionmd/provider/kerneltracingprovider/kerneltracingprovider_linux.go b/x-pack/auditbeat/processors/sessionmd/provider/kerneltracingprovider/kerneltracingprovider_linux.go index d3ec4ba7bd3d..e57c5d693557 100644 --- a/x-pack/auditbeat/processors/sessionmd/provider/kerneltracingprovider/kerneltracingprovider_linux.go +++ b/x-pack/auditbeat/processors/sessionmd/provider/kerneltracingprovider/kerneltracingprovider_linux.go @@ -20,6 +20,7 @@ import ( quark "github.com/elastic/go-quark" + "github.com/elastic/beats/v7/auditbeat/helper/tty" "github.com/elastic/beats/v7/libbeat/beat" "github.com/elastic/beats/v7/x-pack/auditbeat/processors/sessionmd/provider" "github.com/elastic/beats/v7/x-pack/auditbeat/processors/sessionmd/types" @@ -38,15 +39,6 @@ type prvdr struct { backoffSkipped int } -type TTYType int - -const ( - TTYUnknown TTYType = iota - Pts - TTY - TTYConsole -) - const ( Init = "init" Sshd = "sshd" @@ -58,14 +50,6 @@ const ( EntryUnknown = "unknown" ) -const ( - ptsMinMajor = 136 - ptsMaxMajor = 143 - ttyMajor = 4 - consoleMaxMinor = 63 - ttyMaxMinor = 255 -) - var ( bootID string pidNsInode uint64 @@ -241,7 +225,7 @@ func (p *prvdr) GetProcess(pid uint32) (*types.Process, error) { return nil, fmt.Errorf("PID %d not found in cache", pid) } - interactive := interactiveFromTTY(types.TTYDev{ + interactive := tty.InteractiveFromTTY(tty.TTYDev{ Major: proc.Proc.TtyMajor, Minor: proc.Proc.TtyMinor, }) @@ -303,7 +287,7 @@ func (p prvdr) fillParent(process *types.Process, ppid uint32) { } start := time.Unix(0, int64(proc.Proc.TimeBoot)) - interactive := interactiveFromTTY(types.TTYDev{ + interactive := tty.InteractiveFromTTY(tty.TTYDev{ Major: proc.Proc.TtyMajor, Minor: proc.Proc.TtyMinor, }) @@ -338,7 +322,7 @@ func (p prvdr) fillGroupLeader(process *types.Process, pgid uint32) { start := time.Unix(0, int64(proc.Proc.TimeBoot)) - interactive := interactiveFromTTY(types.TTYDev{ + interactive := tty.InteractiveFromTTY(tty.TTYDev{ Major: proc.Proc.TtyMajor, Minor: proc.Proc.TtyMinor, }) @@ -373,7 +357,7 @@ func (p prvdr) fillSessionLeader(process *types.Process, sid uint32) { start := time.Unix(0, int64(proc.Proc.TimeBoot)) - interactive := interactiveFromTTY(types.TTYDev{ + interactive := tty.InteractiveFromTTY(tty.TTYDev{ Major: proc.Proc.TtyMajor, Minor: proc.Proc.TtyMinor, }) @@ -408,7 +392,7 @@ func (p prvdr) fillEntryLeader(process *types.Process, elid uint32) { start := time.Unix(0, int64(proc.Proc.TimeBoot)) - interactive := interactiveFromTTY(types.TTYDev{ + interactive := tty.InteractiveFromTTY(tty.TTYDev{ Major: proc.Proc.TtyMajor, Minor: proc.Proc.TtyMinor, }) @@ -475,28 +459,6 @@ func setSameAsProcess(process *types.Process) { } } -// interactiveFromTTY returns if this is an interactive tty device. -func interactiveFromTTY(tty types.TTYDev) bool { - return TTYUnknown != getTTYType(tty.Major, tty.Minor) -} - -// getTTYType returns the type of a TTY device based on its major and minor numbers. -func getTTYType(major uint32, minor uint32) TTYType { - if major >= ptsMinMajor && major <= ptsMaxMajor { - return Pts - } - - if ttyMajor == major { - if minor <= consoleMaxMinor { - return TTYConsole - } else if minor > consoleMaxMinor && minor <= ttyMaxMinor { - return TTY - } - } - - return TTYUnknown -} - // calculateEntityIDv1 calculates the entity ID for a process. // This is a globally unique identifier for the process. func calculateEntityIDv1(pid uint32, startTime time.Time) string { diff --git a/x-pack/auditbeat/processors/sessionmd/types/events.go b/x-pack/auditbeat/processors/sessionmd/types/events.go index 857ab8fa2c10..2f5cc3109e9d 100644 --- a/x-pack/auditbeat/processors/sessionmd/types/events.go +++ b/x-pack/auditbeat/processors/sessionmd/types/events.go @@ -6,6 +6,8 @@ package types //go:generate stringer -linecomment=true -type=Type,HookPoint,Field -output=gen_types_string.go +import "github.com/elastic/beats/v7/auditbeat/helper/tty" + type Type uint64 const ( @@ -47,25 +49,6 @@ type CredInfo struct { CapEffective uint64 } -type TTYWinsize struct { - Rows uint16 - Cols uint16 -} - -type TTYTermios struct { - CIflag uint32 - COflag uint32 - CLflag uint32 - CCflag uint32 -} - -type TTYDev struct { - Minor uint32 - Major uint32 - Winsize TTYWinsize - Termios TTYTermios -} - type ProcessForkEvent struct { ParentPIDs PIDInfo ChildPIDs PIDInfo @@ -75,7 +58,7 @@ type ProcessForkEvent struct { type ProcessExecEvent struct { PIDs PIDInfo Creds CredInfo - CTTY TTYDev + CTTY tty.TTYDev // varlen fields CWD string From 8daf348229901c0e59c3ce1097d3989ca158e7f9 Mon Sep 17 00:00:00 2001 From: Shaunak Kashyap Date: Thu, 12 Dec 2024 05:54:46 -0800 Subject: [PATCH 45/48] Update CODEOWNERS according to k8s ownership transfer plan (#41858) --- .github/CODEOWNERS | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS index a06730335729..7d3d09d1e78e 100644 --- a/.github/CODEOWNERS +++ b/.github/CODEOWNERS @@ -26,9 +26,9 @@ CHANGELOG* /.github/CODEOWNERS @elastic/beats-tech-leads /auditbeat/ @elastic/sec-linux-platform /deploy/ @elastic/elastic-agent-data-plane -/deploy/kubernetes @elastic/elastic-agent-data-plane @elastic/obs-cloudnative-monitoring +/deploy/kubernetes @elastic/elastic-agent-data-plane @elastic/elastic-agent-control-plane /dev-tools/ @elastic/elastic-agent-data-plane -/dev-tools/kubernetes @elastic/obs-ds-hosted-services +/dev-tools/kubernetes @elastic/elastic-agent-data-plane @elastic/elastic-agent-control-plane /docs/ @elastic/elastic-agent-data-plane /filebeat @elastic/elastic-agent-data-plane /filebeat/docs/ # Listed without an owner to avoid maintaining doc ownership for each input and module. @@ -57,10 +57,11 @@ CHANGELOG* /heartbeat/ @elastic/obs-ds-hosted-services /journalbeat @elastic/elastic-agent-data-plane /libbeat/ @elastic/elastic-agent-data-plane +/libbeat/autodiscover/providers/kubernetes @elastic/elastic-agent-data-plane @elastic/elastic-agent-control-plane /libbeat/docs/processors-list.asciidoc @elastic/ingest-docs /libbeat/management @elastic/elastic-agent-control-plane /libbeat/processors/add_cloud_metadata @elastic/obs-ds-hosted-services -/libbeat/processors/add_kubernetes_metadata @elastic/obs-cloudnative-monitoring +/libbeat/processors/add_kubernetes_metadata @elastic/elastic-agent-data-plane /libbeat/processors/cache/ @elastic/security-service-integrations /libbeat/processors/community_id/ @elastic/sec-deployment-and-devices /libbeat/processors/decode_xml/ @elastic/security-service-integrations From 58af1537830bf314698d760f17ba0b051f2b1dc0 Mon Sep 17 00:00:00 2001 From: Vihas Makwana <121151420+VihasMakwana@users.noreply.github.com> Date: Fri, 13 Dec 2024 01:48:05 +0530 Subject: [PATCH 46/48] [system/cpu][system/core] - New config for using performance counters (#41965) * chore: initial commit * chore: core * chore: go.mod * lint * chore: docs and yaml * chore: docs and yaml * update changelog * fix changelog * notice and go.mod * more specific changelog * chore: default to true * docs --- CHANGELOG.next.asciidoc | 1 + NOTICE.txt | 4 +-- go.mod | 2 +- go.sum | 4 +-- metricbeat/docs/modules/system.asciidoc | 5 ++++ metricbeat/metricbeat.reference.yml | 5 ++++ .../module/system/_meta/config.reference.yml | 5 ++++ .../module/system/core/_meta/docs.asciidoc | 5 ++++ metricbeat/module/system/core/config.go | 8 +++--- metricbeat/module/system/core/core.go | 22 +++++++++++++--- .../module/system/cpu/_meta/docs.asciidoc | 5 ++++ metricbeat/module/system/cpu/config.go | 8 +++--- metricbeat/module/system/cpu/cpu.go | 25 ++++++++++++++----- x-pack/metricbeat/metricbeat.reference.yml | 5 ++++ 14 files changed, 83 insertions(+), 21 deletions(-) diff --git a/CHANGELOG.next.asciidoc b/CHANGELOG.next.asciidoc index 11e20daeacb7..dd4f533a64ae 100644 --- a/CHANGELOG.next.asciidoc +++ b/CHANGELOG.next.asciidoc @@ -420,6 +420,7 @@ https://github.com/elastic/beats/compare/v8.8.1\...main[Check the HEAD diff] - Add support for region/zone for Vertex AI service in GCP module {pull}41551[41551] - Add support for location label as an optional configuration parameter in GCP metrics metricset. {issue}41550[41550] {pull}41626[41626] - Added `tier_preference`, `creation_date` and `version` fields to the `elasticsearch.index` metricset. {pull}41944[41944] +- Add `use_performance_counters` to collect CPU metrics using performance counters on Windows for `system/cpu` and `system/core` {pull}41965[41965] *Metricbeat* - Add benchmark module {pull}41801[41801] diff --git a/NOTICE.txt b/NOTICE.txt index dd599cb5cb18..ae812a0cbccd 100644 --- a/NOTICE.txt +++ b/NOTICE.txt @@ -12699,11 +12699,11 @@ Contents of probable licence file $GOMODCACHE/github.com/elastic/elastic-agent-l -------------------------------------------------------------------------------- Dependency : github.com/elastic/elastic-agent-system-metrics -Version: v0.11.4 +Version: v0.11.5 Licence type (autodetected): Apache-2.0 -------------------------------------------------------------------------------- -Contents of probable licence file $GOMODCACHE/github.com/elastic/elastic-agent-system-metrics@v0.11.4/LICENSE.txt: +Contents of probable licence file $GOMODCACHE/github.com/elastic/elastic-agent-system-metrics@v0.11.5/LICENSE.txt: Apache License Version 2.0, January 2004 diff --git a/go.mod b/go.mod index 2e25c7c9de0d..77abb4800d16 100644 --- a/go.mod +++ b/go.mod @@ -178,7 +178,7 @@ require ( github.com/elastic/ebpfevents v0.6.0 github.com/elastic/elastic-agent-autodiscover v0.9.0 github.com/elastic/elastic-agent-libs v0.17.4 - github.com/elastic/elastic-agent-system-metrics v0.11.4 + github.com/elastic/elastic-agent-system-metrics v0.11.5 github.com/elastic/go-elasticsearch/v8 v8.14.0 github.com/elastic/go-quark v0.2.0 github.com/elastic/go-sfdc v0.0.0-20241010131323-8e176480d727 diff --git a/go.sum b/go.sum index cbf4b3eab9ea..2e45c13cbd3c 100644 --- a/go.sum +++ b/go.sum @@ -324,8 +324,8 @@ github.com/elastic/elastic-agent-client/v7 v7.15.0 h1:nDB7v8TBoNuD6IIzC3z7Q0y+7b github.com/elastic/elastic-agent-client/v7 v7.15.0/go.mod h1:6h+f9QdIr3GO2ODC0Y8+aEXRwzbA5W4eV4dd/67z7nI= github.com/elastic/elastic-agent-libs v0.17.4 h1:kWK5Kn2EQjM97yHqbeXv+cFAIti4IiI9Qj8huM+lZzE= github.com/elastic/elastic-agent-libs v0.17.4/go.mod h1:5CR02awPrBr+tfmjBBK+JI+dMmHNQjpVY24J0wjbC7M= -github.com/elastic/elastic-agent-system-metrics v0.11.4 h1:Z/8CML5RKvGpi6/QUFok1K3EriBAv2kUAXnsk8hCifk= -github.com/elastic/elastic-agent-system-metrics v0.11.4/go.mod h1:TTW2ysv78uHBQ68hG8TXiaX1m6f29ZHgGWb8XONYsU8= +github.com/elastic/elastic-agent-system-metrics v0.11.5 h1:JSjXFEn8uYZ9hoC/GxZNMgJ622UoP96sjYP/49/Uvuo= +github.com/elastic/elastic-agent-system-metrics v0.11.5/go.mod h1:nzkrGajQA29YNcfP62gfzhxX9an3/xdQ3RmfQNw9YTI= github.com/elastic/elastic-transport-go/v8 v8.6.0 h1:Y2S/FBjx1LlCv5m6pWAF2kDJAHoSjSRSJCApolgfthA= github.com/elastic/elastic-transport-go/v8 v8.6.0/go.mod h1:YLHer5cj0csTzNFXoNQ8qhtGY1GTvSqPnKWKaqQE3Hk= github.com/elastic/fsevents v0.0.0-20181029231046-e1d381a4d270 h1:cWPqxlPtir4RoQVCpGSRXmLqjEHpJKbR60rxh1nQZY4= diff --git a/metricbeat/docs/modules/system.asciidoc b/metricbeat/docs/modules/system.asciidoc index 2fc3930d8444..164abe5c91e3 100644 --- a/metricbeat/docs/modules/system.asciidoc +++ b/metricbeat/docs/modules/system.asciidoc @@ -265,6 +265,11 @@ metricbeat.modules: # Filter systemd services based on a name pattern #service.pattern_filter: ["ssh*", "nfs*"] + + # This option enables the use of performance counters to collect data for cpu/core metricset. + # Only effective for Windows. + # You should use this option if running beats on machins with more than 64 cores. + #use_performance_counters: true ---- [float] diff --git a/metricbeat/metricbeat.reference.yml b/metricbeat/metricbeat.reference.yml index f1412be4b6f2..6cb4352b87d6 100644 --- a/metricbeat/metricbeat.reference.yml +++ b/metricbeat/metricbeat.reference.yml @@ -142,6 +142,11 @@ metricbeat.modules: # Filter systemd services based on a name pattern #service.pattern_filter: ["ssh*", "nfs*"] + # This option enables the use of performance counters to collect data for cpu/core metricset. + # Only effective for Windows. + # You should use this option if running beats on machins with more than 64 cores. + #use_performance_counters: true + #------------------------------ Aerospike Module ------------------------------ - module: aerospike metricsets: ["namespace"] diff --git a/metricbeat/module/system/_meta/config.reference.yml b/metricbeat/module/system/_meta/config.reference.yml index 974df87cb0bc..777a6444ecae 100644 --- a/metricbeat/module/system/_meta/config.reference.yml +++ b/metricbeat/module/system/_meta/config.reference.yml @@ -81,3 +81,8 @@ # Filter systemd services based on a name pattern #service.pattern_filter: ["ssh*", "nfs*"] + + # This option enables the use of performance counters to collect data for cpu/core metricset. + # Only effective for Windows. + # You should use this option if running beats on machins with more than 64 cores. + #use_performance_counters: true diff --git a/metricbeat/module/system/core/_meta/docs.asciidoc b/metricbeat/module/system/core/_meta/docs.asciidoc index e70e55f0db71..751c4759a9c3 100644 --- a/metricbeat/module/system/core/_meta/docs.asciidoc +++ b/metricbeat/module/system/core/_meta/docs.asciidoc @@ -14,6 +14,10 @@ This metricset is available on: *`core.metrics`*:: This option controls what metrics are reported for each CPU core. The value is a list and two metric types are supported - `percentages` and `ticks`. The default value is `core.metrics: [percentages]`. +*`use_performance_counters`*:: This option enables the use of performance counters to +collect data for the CPU/core metricset. It is only effective on Windows. +You should use this option if running beats on machins with more than 64 cores. +The default value is `use_performance_counters: true` + [source,yaml] ---- @@ -21,4 +25,5 @@ metricbeat.modules: - module: system metricsets: [core] core.metrics: [percentages, ticks] + #use_performance_counters: true ---- diff --git a/metricbeat/module/system/core/config.go b/metricbeat/module/system/core/config.go index 8ac1d2f9575a..940a23282165 100644 --- a/metricbeat/module/system/core/config.go +++ b/metricbeat/module/system/core/config.go @@ -34,8 +34,9 @@ const ( // Config for the system core metricset. type Config struct { - Metrics []string `config:"core.metrics"` - CPUTicks *bool `config:"cpu_ticks"` // Deprecated. + Metrics []string `config:"core.metrics"` + CPUTicks *bool `config:"cpu_ticks"` // Deprecated. + UserPerformanceCounters bool `config:"use_performance_counters"` } // Validate validates the core config. @@ -65,5 +66,6 @@ func (c Config) Validate() (metrics.MetricOpts, error) { } var defaultConfig = Config{ - Metrics: []string{percentages}, + Metrics: []string{percentages}, + UserPerformanceCounters: true, } diff --git a/metricbeat/module/system/core/core.go b/metricbeat/module/system/core/core.go index 1bf2f3f3a3db..fc5e7b9e3945 100644 --- a/metricbeat/module/system/core/core.go +++ b/metricbeat/module/system/core/core.go @@ -41,6 +41,7 @@ type MetricSet struct { mb.BaseMetricSet opts metrics.MetricOpts cores *metrics.Monitor + sys resolve.Resolver } // New returns a new core MetricSet. @@ -58,11 +59,25 @@ func New(base mb.BaseMetricSet) (mb.MetricSet, error) { if config.CPUTicks != nil && *config.CPUTicks { config.Metrics = append(config.Metrics, "ticks") } - sys := base.Module().(resolve.Resolver) + sys, ok := base.Module().(resolve.Resolver) + if !ok { + return nil, fmt.Errorf("unexpected module type: %T", base.Module()) + } + + cpuOpts := make([]metrics.OptionFunc, 0) + if config.UserPerformanceCounters { + cpuOpts = append(cpuOpts, metrics.WithWindowsPerformanceCounter()) + } + cpu, err := metrics.New(sys, cpuOpts...) + if err != nil { + return nil, fmt.Errorf("error initializing system.cpu metricset: %w", err) + } + return &MetricSet{ BaseMetricSet: base, opts: opts, - cores: metrics.New(sys), + cores: cpu, + sys: sys, }, nil } @@ -109,6 +124,5 @@ func (m *MetricSet) Diagnostics() []diagnostics.DiagnosticSetup { } func (m *MetricSet) getDiagData() []byte { - sys := m.BaseMetricSet.Module().(resolve.Resolver) - return diagnostics.GetRawFileOrErrorString(sys, "/proc/stat") + return diagnostics.GetRawFileOrErrorString(m.sys, "/proc/stat") } diff --git a/metricbeat/module/system/cpu/_meta/docs.asciidoc b/metricbeat/module/system/cpu/_meta/docs.asciidoc index fb83c41e500a..b0d9da584591 100644 --- a/metricbeat/module/system/cpu/_meta/docs.asciidoc +++ b/metricbeat/module/system/cpu/_meta/docs.asciidoc @@ -15,6 +15,10 @@ This metricset is available on: is a list and three metric types are supported - `percentages`, `normalized_percentages`, and `ticks`. The default value is `cpu.metrics: [percentages]`. +*`use_performance_counters`*:: This option enables the use of performance counters to +collect data for the CPU/core metricset. It is only effective on Windows. +You should use this option if running beats on machins with more than 64 cores. +The default value is `use_performance_counters: true` + [source,yaml] ---- @@ -22,4 +26,5 @@ metricbeat.modules: - module: system metricsets: [cpu] cpu.metrics: [percentages, normalized_percentages, ticks] + #use_performance_counters: true ---- diff --git a/metricbeat/module/system/cpu/config.go b/metricbeat/module/system/cpu/config.go index ef9d78fe0ced..7cfffed57a53 100644 --- a/metricbeat/module/system/cpu/config.go +++ b/metricbeat/module/system/cpu/config.go @@ -35,8 +35,9 @@ const ( // Config for the system cpu metricset. type Config struct { - Metrics []string `config:"cpu.metrics"` - CPUTicks *bool `config:"cpu_ticks"` // Deprecated. + Metrics []string `config:"cpu.metrics"` + CPUTicks *bool `config:"cpu_ticks"` // Deprecated. + UserPerformanceCounters bool `config:"use_performance_counters"` } // Validate validates the cpu config. @@ -69,5 +70,6 @@ func (c Config) Validate() (metrics.MetricOpts, error) { } var defaultConfig = Config{ - Metrics: []string{percentages, normalizedPercentages}, + Metrics: []string{percentages, normalizedPercentages}, + UserPerformanceCounters: true, } diff --git a/metricbeat/module/system/cpu/cpu.go b/metricbeat/module/system/cpu/cpu.go index 8eb06c2427bd..ace37b809e85 100644 --- a/metricbeat/module/system/cpu/cpu.go +++ b/metricbeat/module/system/cpu/cpu.go @@ -44,6 +44,7 @@ type MetricSet struct { mb.BaseMetricSet opts metrics.MetricOpts cpu *metrics.Monitor + sys resolve.Resolver } // New is a mb.MetricSetFactory that returns a cpu.MetricSet. @@ -61,11 +62,25 @@ func New(base mb.BaseMetricSet) (mb.MetricSet, error) { if config.CPUTicks != nil && *config.CPUTicks { config.Metrics = append(config.Metrics, "ticks") } - sys := base.Module().(resolve.Resolver) + sys, ok := base.Module().(resolve.Resolver) + if !ok { + return nil, fmt.Errorf("unexpected module type: %T", base.Module()) + } + + cpuOpts := make([]metrics.OptionFunc, 0) + if config.UserPerformanceCounters { + cpuOpts = append(cpuOpts, metrics.WithWindowsPerformanceCounter()) + } + cpu, err := metrics.New(sys, cpuOpts...) + + if err != nil { + return nil, fmt.Errorf("error initializing system.cpu metricset: %w", err) + } return &MetricSet{ BaseMetricSet: base, opts: opts, - cpu: metrics.New(sys), + cpu: cpu, + sys: sys, }, nil } @@ -125,13 +140,11 @@ func (m *MetricSet) Diagnostics() []diagnostics.DiagnosticSetup { } func (m *MetricSet) fetchRawCPU() []byte { - sys := m.BaseMetricSet.Module().(resolve.Resolver) - return diagnostics.GetRawFileOrErrorString(sys, "/proc/stat") + return diagnostics.GetRawFileOrErrorString(m.sys, "/proc/stat") } func (m *MetricSet) fetchCPUInfo() []byte { - sys := m.BaseMetricSet.Module().(resolve.Resolver) - return diagnostics.GetRawFileOrErrorString(sys, "/proc/cpuinfo") + return diagnostics.GetRawFileOrErrorString(m.sys, "/proc/cpuinfo") } // copyFieldsOrDefault copies the field specified by key to the given map. It will diff --git a/x-pack/metricbeat/metricbeat.reference.yml b/x-pack/metricbeat/metricbeat.reference.yml index 8c4250caecea..707b6419d9ed 100644 --- a/x-pack/metricbeat/metricbeat.reference.yml +++ b/x-pack/metricbeat/metricbeat.reference.yml @@ -142,6 +142,11 @@ metricbeat.modules: # Filter systemd services based on a name pattern #service.pattern_filter: ["ssh*", "nfs*"] + # This option enables the use of performance counters to collect data for cpu/core metricset. + # Only effective for Windows. + # You should use this option if running beats on machins with more than 64 cores. + #use_performance_counters: true + #------------------------------- ActiveMQ Module ------------------------------- - module: activemq metricsets: ['broker', 'queue', 'topic'] From 5ed055bb9dd4c5a4733f00800892d65debd897d8 Mon Sep 17 00:00:00 2001 From: ShourieG Date: Fri, 13 Dec 2024 15:04:04 +0530 Subject: [PATCH 47/48] [filebeat][streaming] - Added default values for websocket retries & put a cap on waitTime to be <= waitMax (#42012) * added default retry values and ensured a cap on waitTime i.e now waitTime <= wait_max * updated changelog --- CHANGELOG.next.asciidoc | 1 + x-pack/filebeat/docs/inputs/input-streaming.asciidoc | 6 +++--- x-pack/filebeat/input/streaming/config.go | 5 +++++ x-pack/filebeat/input/streaming/websocket.go | 4 ++++ 4 files changed, 13 insertions(+), 3 deletions(-) diff --git a/CHANGELOG.next.asciidoc b/CHANGELOG.next.asciidoc index dd4f533a64ae..f0964ce15452 100644 --- a/CHANGELOG.next.asciidoc +++ b/CHANGELOG.next.asciidoc @@ -368,6 +368,7 @@ https://github.com/elastic/beats/compare/v8.8.1\...main[Check the HEAD diff] - AWS S3 input registry cleanup for untracked s3 objects. {pull}41694[41694] - The environment variable `BEATS_AZURE_EVENTHUB_INPUT_TRACING_ENABLED: true` enables internal logs tracer for the azure-eventhub input. {issue}41931[41931] {pull}41932[41932] - Rate limiting operability improvements in the Okta provider of the Entity Analytics input. {issue}40106[40106] {pull}41977[41977] +- Added default values in the streaming input for websocket retries and put a cap on retry wait time to be lesser than equal to the maximum defined wait time. {pull}42012[42012] *Auditbeat* diff --git a/x-pack/filebeat/docs/inputs/input-streaming.asciidoc b/x-pack/filebeat/docs/inputs/input-streaming.asciidoc index 9a6f67e5bc49..7f07fb4954f6 100644 --- a/x-pack/filebeat/docs/inputs/input-streaming.asciidoc +++ b/x-pack/filebeat/docs/inputs/input-streaming.asciidoc @@ -337,17 +337,17 @@ filebeat.inputs: [float] ==== `retry.max_attempts` -The maximum number of times the input should attempt to reconnect to the streaming data source in the event of a connection failure. The default value is `nil` which means no retries will be attempted. +The maximum number of times the input should attempt to reconnect to the streaming data source in the event of a connection failure. The default value is `5` which means a maximum of 5 retries will be attempted. [float] ==== `retry.wait_min` -The minimum time to wait between retries. This ensures that retries are spaced out enough to give the system time to recover or resolve transient issues, rather than bombarding the system with rapid retries. For example, `wait_min` might be set to 1 second, meaning that even if the calculated backoff is less than this, the client will wait at least 1 second before retrying. +The minimum time to wait between retries. This ensures that retries are spaced out enough to give the system time to recover or resolve transient issues, rather than bombarding the system with rapid retries. For example, `wait_min` might be set to 1 second, meaning that even if the calculated backoff is less than this, the client will wait at least 1 second before retrying. The default value is `1` second. [float] ==== `retry.wait_max` -The maximum time to wait between retries. This prevents the retry mechanism from becoming too slow, ensuring that the client does not wait indefinitely between retries. This is crucial in systems where timeouts or user experience are critical. For example, `wait_max` might be set to 10 seconds, meaning that even if the calculated backoff is greater than this, the client will wait at most 10 seconds before retrying. +The maximum time to wait between retries. This prevents the retry mechanism from becoming too slow, ensuring that the client does not wait indefinitely between retries. This is crucial in systems where timeouts or user experience are critical. For example, `wait_max` might be set to 10 seconds, meaning that even if the calculated backoff is greater than this, the client will wait at most 10 seconds before retrying. The default value is `30` seconds. [float] === `timeout` diff --git a/x-pack/filebeat/input/streaming/config.go b/x-pack/filebeat/input/streaming/config.go index 6ccaf0c73493..eea8c2afc704 100644 --- a/x-pack/filebeat/input/streaming/config.go +++ b/x-pack/filebeat/input/streaming/config.go @@ -171,5 +171,10 @@ func defaultConfig() config { Transport: httpcommon.HTTPTransportSettings{ Timeout: 180 * time.Second, }, + Retry: &retry{ + MaxAttempts: 5, + WaitMin: 1 * time.Second, + WaitMax: 30 * time.Second, + }, } } diff --git a/x-pack/filebeat/input/streaming/websocket.go b/x-pack/filebeat/input/streaming/websocket.go index 8a78757f0e96..8a8cf76fe361 100644 --- a/x-pack/filebeat/input/streaming/websocket.go +++ b/x-pack/filebeat/input/streaming/websocket.go @@ -261,6 +261,10 @@ func calculateWaitTime(waitMin, waitMax time.Duration, attempt int) time.Duratio jitter := rand.Float64() * maxJitter waitTime := time.Duration(backoff + jitter) + // caps the wait time to the maximum wait time + if waitTime > waitMax { + waitTime = waitMax + } return waitTime } From 93b018a8362139eeb6b81bde9c43374c7ad1cd46 Mon Sep 17 00:00:00 2001 From: subham sarkar Date: Fri, 13 Dec 2024 16:16:05 +0530 Subject: [PATCH 48/48] x-pack/metricbeat/module/openai: Add new module (#41516) --- .github/CODEOWNERS | 1 + metricbeat/docs/fields.asciidoc | 367 +++++++++++++ metricbeat/docs/modules/openai.asciidoc | 75 +++ metricbeat/docs/modules/openai/usage.asciidoc | 29 ++ metricbeat/docs/modules_list.asciidoc | 3 + x-pack/agentbeat/agentbeat.spec.yml | 5 + x-pack/metricbeat/include/list.go | 2 + x-pack/metricbeat/metricbeat.reference.yml | 36 ++ .../metricbeat/module/openai/_meta/config.yml | 34 ++ .../module/openai/_meta/docs.asciidoc | 2 + .../metricbeat/module/openai/_meta/fields.yml | 10 + x-pack/metricbeat/module/openai/doc.go | 6 + x-pack/metricbeat/module/openai/fields.go | 23 + .../module/openai/usage/_meta/data.json | 37 ++ .../module/openai/usage/_meta/docs.asciidoc | 1 + .../module/openai/usage/_meta/fields.yml | 156 ++++++ .../metricbeat/module/openai/usage/client.go | 71 +++ .../metricbeat/module/openai/usage/config.go | 94 ++++ .../metricbeat/module/openai/usage/errors.go | 10 + .../metricbeat/module/openai/usage/helper.go | 30 ++ .../module/openai/usage/persistcache.go | 187 +++++++ .../metricbeat/module/openai/usage/schema.go | 69 +++ .../metricbeat/module/openai/usage/usage.go | 387 ++++++++++++++ .../openai/usage/usage_integration_test.go | 482 ++++++++++++++++++ .../metricbeat/modules.d/openai.yml.disabled | 37 ++ 25 files changed, 2154 insertions(+) create mode 100644 metricbeat/docs/modules/openai.asciidoc create mode 100644 metricbeat/docs/modules/openai/usage.asciidoc create mode 100644 x-pack/metricbeat/module/openai/_meta/config.yml create mode 100644 x-pack/metricbeat/module/openai/_meta/docs.asciidoc create mode 100644 x-pack/metricbeat/module/openai/_meta/fields.yml create mode 100644 x-pack/metricbeat/module/openai/doc.go create mode 100644 x-pack/metricbeat/module/openai/fields.go create mode 100644 x-pack/metricbeat/module/openai/usage/_meta/data.json create mode 100644 x-pack/metricbeat/module/openai/usage/_meta/docs.asciidoc create mode 100644 x-pack/metricbeat/module/openai/usage/_meta/fields.yml create mode 100644 x-pack/metricbeat/module/openai/usage/client.go create mode 100644 x-pack/metricbeat/module/openai/usage/config.go create mode 100644 x-pack/metricbeat/module/openai/usage/errors.go create mode 100644 x-pack/metricbeat/module/openai/usage/helper.go create mode 100644 x-pack/metricbeat/module/openai/usage/persistcache.go create mode 100644 x-pack/metricbeat/module/openai/usage/schema.go create mode 100644 x-pack/metricbeat/module/openai/usage/usage.go create mode 100644 x-pack/metricbeat/module/openai/usage/usage_integration_test.go create mode 100644 x-pack/metricbeat/modules.d/openai.yml.disabled diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS index 7d3d09d1e78e..1a8fd0a00882 100644 --- a/.github/CODEOWNERS +++ b/.github/CODEOWNERS @@ -223,6 +223,7 @@ CHANGELOG* /x-pack/metricbeat/module/iis @elastic/obs-infraobs-integrations /x-pack/metricbeat/module/istio/ @elastic/obs-cloudnative-monitoring /x-pack/metricbeat/module/mssql @elastic/obs-infraobs-integrations +/x-pack/metricbeat/module/openai @elastic/obs-infraobs-integrations /x-pack/metricbeat/module/oracle @elastic/obs-infraobs-integrations /x-pack/metricbeat/module/panw @elastic/obs-infraobs-integrations /x-pack/metricbeat/module/prometheus/ @elastic/obs-cloudnative-monitoring diff --git a/metricbeat/docs/fields.asciidoc b/metricbeat/docs/fields.asciidoc index 967c20f14cfa..103bdd718350 100644 --- a/metricbeat/docs/fields.asciidoc +++ b/metricbeat/docs/fields.asciidoc @@ -68,6 +68,7 @@ grouped in the following categories: * <> * <> * <> +* <> * <> * <> * <> @@ -56706,6 +56707,372 @@ type: long -- +[[exported-fields-openai]] +== openai fields + +openai module + + + +[float] +=== openai + + + + +[float] +=== usage + +OpenAI API usage metrics and statistics + + + +*`openai.usage.organization_id`*:: ++ +-- +Organization identifier + +type: keyword + +-- + +*`openai.usage.organization_name`*:: ++ +-- +Organization name + +type: keyword + +-- + +*`openai.usage.api_key_id`*:: ++ +-- +API key identifier + +type: keyword + +-- + +*`openai.usage.api_key_name`*:: ++ +-- +API key name + +type: keyword + +-- + +*`openai.usage.api_key_redacted`*:: ++ +-- +Redacted API key + +type: keyword + +-- + +*`openai.usage.api_key_type`*:: ++ +-- +Type of API key + +type: keyword + +-- + +*`openai.usage.project_id`*:: ++ +-- +Project identifier + +type: keyword + +-- + +*`openai.usage.project_name`*:: ++ +-- +Project name + +type: keyword + +-- + +[float] +=== data + +General usage data metrics + + + +*`openai.usage.data.requests_total`*:: ++ +-- +Number of requests made + +type: long + +-- + +*`openai.usage.data.operation`*:: ++ +-- +Operation type + +type: keyword + +-- + +*`openai.usage.data.snapshot_id`*:: ++ +-- +Snapshot identifier + +type: keyword + +-- + +*`openai.usage.data.context_tokens_total`*:: ++ +-- +Total number of context tokens used + +type: long + +-- + +*`openai.usage.data.generated_tokens_total`*:: ++ +-- +Total number of generated tokens + +type: long + +-- + +*`openai.usage.data.cached_context_tokens_total`*:: ++ +-- +Total number of cached context tokens + +type: long + +-- + +*`openai.usage.data.email`*:: ++ +-- +User email + +type: keyword + +-- + +*`openai.usage.data.request_type`*:: ++ +-- +Type of request + +type: keyword + +-- + +[float] +=== dalle + +DALL-E API usage metrics + + + +*`openai.usage.dalle.num_images`*:: ++ +-- +Number of images generated + +type: long + +-- + +*`openai.usage.dalle.requests_total`*:: ++ +-- +Number of requests + +type: long + +-- + +*`openai.usage.dalle.image_size`*:: ++ +-- +Size of generated images + +type: keyword + +-- + +*`openai.usage.dalle.operation`*:: ++ +-- +Operation type + +type: keyword + +-- + +*`openai.usage.dalle.user_id`*:: ++ +-- +User identifier + +type: keyword + +-- + +*`openai.usage.dalle.model_id`*:: ++ +-- +Model identifier + +type: keyword + +-- + +[float] +=== whisper + +Whisper API usage metrics + + + +*`openai.usage.whisper.model_id`*:: ++ +-- +Model identifier + +type: keyword + +-- + +*`openai.usage.whisper.num_seconds`*:: ++ +-- +Number of seconds processed + +type: long + +-- + +*`openai.usage.whisper.requests_total`*:: ++ +-- +Number of requests + +type: long + +-- + +*`openai.usage.whisper.user_id`*:: ++ +-- +User identifier + +type: keyword + +-- + +[float] +=== tts + +Text-to-Speech API usage metrics + + + +*`openai.usage.tts.model_id`*:: ++ +-- +Model identifier + +type: keyword + +-- + +*`openai.usage.tts.num_characters`*:: ++ +-- +Number of characters processed + +type: long + +-- + +*`openai.usage.tts.requests_total`*:: ++ +-- +Number of requests + +type: long + +-- + +*`openai.usage.tts.user_id`*:: ++ +-- +User identifier + +type: keyword + +-- + +[float] +=== ft_data + +Fine-tuning data metrics + + + +*`openai.usage.ft_data.original`*:: ++ +-- +Raw fine-tuning data + +type: object + +-- + +[float] +=== assistant_code_interpreter + +Assistant Code Interpreter usage metrics + + + +*`openai.usage.assistant_code_interpreter.original`*:: ++ +-- +Raw assistant code interpreter data + +type: object + +-- + +[float] +=== retrieval_storage + +Retrieval storage usage metrics + + + +*`openai.usage.retrieval_storage.original`*:: ++ +-- +Raw retrieval storage data + +type: object + +-- + [[exported-fields-openmetrics]] == Openmetrics fields diff --git a/metricbeat/docs/modules/openai.asciidoc b/metricbeat/docs/modules/openai.asciidoc new file mode 100644 index 000000000000..ce5fd3e0ccc5 --- /dev/null +++ b/metricbeat/docs/modules/openai.asciidoc @@ -0,0 +1,75 @@ +//// +This file is generated! See scripts/mage/docs_collector.go +//// + +:modulename: openai +:edit_url: https://github.com/elastic/beats/edit/main/x-pack/metricbeat/module/openai/_meta/docs.asciidoc + + +[[metricbeat-module-openai]] +[role="xpack"] +== openai module + +beta[] + +This is the openai module. + + + +:edit_url: + +[float] +=== Example configuration + +The openai module supports the standard configuration options that are described +in <>. Here is an example configuration: + +[source,yaml] +---- +metricbeat.modules: +- module: openai + metricsets: ["usage"] + enabled: false + period: 1h + + # # Project API Keys - Multiple API keys can be specified for different projects + # api_keys: + # - key: "api_key1" + # - key: "api_key2" + + # # API Configuration + # ## Base URL for the OpenAI usage API endpoint + # api_url: "https://api.openai.com/v1/usage" + # ## Custom headers to be included in API requests + # headers: + # - "k1: v1" + # - "k2: v2" + ## Rate Limiting Configuration + # rate_limit: + # limit: 12 # seconds between requests + # burst: 1 # max concurrent requests + # ## Request Timeout Duration + # timeout: 30s + + # # Data Collection Configuration + # collection: + # ## Number of days to look back when collecting usage data + # lookback_days: 30 + # ## Whether to collect usage data in realtime. Defaults to false as how + # # OpenAI usage data is collected will end up adding duplicate data to ES + # # and also making it harder to do analytics. Best approach is to avoid + # # realtime collection and collect only upto last day (in UTC). So, there's + # # at most 24h delay. + # realtime: false +---- + +[float] +=== Metricsets + +The following metricsets are available: + +* <> + +include::openai/usage.asciidoc[] + +:edit_url!: diff --git a/metricbeat/docs/modules/openai/usage.asciidoc b/metricbeat/docs/modules/openai/usage.asciidoc new file mode 100644 index 000000000000..69d0ba313d9c --- /dev/null +++ b/metricbeat/docs/modules/openai/usage.asciidoc @@ -0,0 +1,29 @@ +//// +This file is generated! See scripts/mage/docs_collector.go +//// +:edit_url: https://github.com/elastic/beats/edit/main/x-pack/metricbeat/module/openai/usage/_meta/docs.asciidoc + + +[[metricbeat-metricset-openai-usage]] +[role="xpack"] +=== openai usage metricset + +beta[] + +include::../../../../x-pack/metricbeat/module/openai/usage/_meta/docs.asciidoc[] + + +:edit_url: + +==== Fields + +For a description of each field in the metricset, see the +<> section. + +Here is an example document generated by this metricset: + +[source,json] +---- +include::../../../../x-pack/metricbeat/module/openai/usage/_meta/data.json[] +---- +:edit_url!: \ No newline at end of file diff --git a/metricbeat/docs/modules_list.asciidoc b/metricbeat/docs/modules_list.asciidoc index abf04650f2ca..ae81c25e5fc9 100644 --- a/metricbeat/docs/modules_list.asciidoc +++ b/metricbeat/docs/modules_list.asciidoc @@ -242,6 +242,8 @@ This file is generated! See scripts/mage/docs_collector.go |<> |<> |image:./images/icon-yes.png[Prebuilt dashboards are available] | .1+| .1+| |<> +|<> beta[] |image:./images/icon-no.png[No prebuilt dashboards] | +.1+| .1+| |<> beta[] |<> beta[] |image:./images/icon-no.png[No prebuilt dashboards] | .1+| .1+| |<> beta[] |<> |image:./images/icon-yes.png[Prebuilt dashboards are available] | @@ -384,6 +386,7 @@ include::modules/munin.asciidoc[] include::modules/mysql.asciidoc[] include::modules/nats.asciidoc[] include::modules/nginx.asciidoc[] +include::modules/openai.asciidoc[] include::modules/openmetrics.asciidoc[] include::modules/oracle.asciidoc[] include::modules/panw.asciidoc[] diff --git a/x-pack/agentbeat/agentbeat.spec.yml b/x-pack/agentbeat/agentbeat.spec.yml index a2af5ce6bf8f..5b6c33e4ceb1 100644 --- a/x-pack/agentbeat/agentbeat.spec.yml +++ b/x-pack/agentbeat/agentbeat.spec.yml @@ -507,6 +507,11 @@ inputs: platforms: *platforms outputs: *outputs command: *metricbeat_command + - name: openai/metrics + description: "OpenAI metrics" + platforms: *platforms + outputs: *outputs + command: *metricbeat_command - name: panw/metrics description: "Palo Alto Networks metrics" platforms: *platforms diff --git a/x-pack/metricbeat/include/list.go b/x-pack/metricbeat/include/list.go index b9b426cf0add..af3b1e9425d8 100644 --- a/x-pack/metricbeat/include/list.go +++ b/x-pack/metricbeat/include/list.go @@ -55,6 +55,8 @@ import ( _ "github.com/elastic/beats/v7/x-pack/metricbeat/module/mssql" _ "github.com/elastic/beats/v7/x-pack/metricbeat/module/mssql/performance" _ "github.com/elastic/beats/v7/x-pack/metricbeat/module/mssql/transaction_log" + _ "github.com/elastic/beats/v7/x-pack/metricbeat/module/openai" + _ "github.com/elastic/beats/v7/x-pack/metricbeat/module/openai/usage" _ "github.com/elastic/beats/v7/x-pack/metricbeat/module/oracle" _ "github.com/elastic/beats/v7/x-pack/metricbeat/module/oracle/performance" _ "github.com/elastic/beats/v7/x-pack/metricbeat/module/oracle/sysmetric" diff --git a/x-pack/metricbeat/metricbeat.reference.yml b/x-pack/metricbeat/metricbeat.reference.yml index 707b6419d9ed..1f1f410ce5a3 100644 --- a/x-pack/metricbeat/metricbeat.reference.yml +++ b/x-pack/metricbeat/metricbeat.reference.yml @@ -1284,6 +1284,42 @@ metricbeat.modules: # Path to server status. Default nginx_status server_status_path: "nginx_status" +#-------------------------------- Openai Module -------------------------------- +- module: openai + metricsets: ["usage"] + enabled: false + period: 1h + + # # Project API Keys - Multiple API keys can be specified for different projects + # api_keys: + # - key: "api_key1" + # - key: "api_key2" + + # # API Configuration + # ## Base URL for the OpenAI usage API endpoint + # api_url: "https://api.openai.com/v1/usage" + # ## Custom headers to be included in API requests + # headers: + # - "k1: v1" + # - "k2: v2" + ## Rate Limiting Configuration + # rate_limit: + # limit: 12 # seconds between requests + # burst: 1 # max concurrent requests + # ## Request Timeout Duration + # timeout: 30s + + # # Data Collection Configuration + # collection: + # ## Number of days to look back when collecting usage data + # lookback_days: 30 + # ## Whether to collect usage data in realtime. Defaults to false as how + # # OpenAI usage data is collected will end up adding duplicate data to ES + # # and also making it harder to do analytics. Best approach is to avoid + # # realtime collection and collect only upto last day (in UTC). So, there's + # # at most 24h delay. + # realtime: false + #----------------------------- Openmetrics Module ----------------------------- - module: openmetrics metricsets: ['collector'] diff --git a/x-pack/metricbeat/module/openai/_meta/config.yml b/x-pack/metricbeat/module/openai/_meta/config.yml new file mode 100644 index 000000000000..a34fd7b183de --- /dev/null +++ b/x-pack/metricbeat/module/openai/_meta/config.yml @@ -0,0 +1,34 @@ +- module: openai + metricsets: ["usage"] + enabled: false + period: 1h + + # # Project API Keys - Multiple API keys can be specified for different projects + # api_keys: + # - key: "api_key1" + # - key: "api_key2" + + # # API Configuration + # ## Base URL for the OpenAI usage API endpoint + # api_url: "https://api.openai.com/v1/usage" + # ## Custom headers to be included in API requests + # headers: + # - "k1: v1" + # - "k2: v2" + ## Rate Limiting Configuration + # rate_limit: + # limit: 12 # seconds between requests + # burst: 1 # max concurrent requests + # ## Request Timeout Duration + # timeout: 30s + + # # Data Collection Configuration + # collection: + # ## Number of days to look back when collecting usage data + # lookback_days: 30 + # ## Whether to collect usage data in realtime. Defaults to false as how + # # OpenAI usage data is collected will end up adding duplicate data to ES + # # and also making it harder to do analytics. Best approach is to avoid + # # realtime collection and collect only upto last day (in UTC). So, there's + # # at most 24h delay. + # realtime: false diff --git a/x-pack/metricbeat/module/openai/_meta/docs.asciidoc b/x-pack/metricbeat/module/openai/_meta/docs.asciidoc new file mode 100644 index 000000000000..744909c7a1ab --- /dev/null +++ b/x-pack/metricbeat/module/openai/_meta/docs.asciidoc @@ -0,0 +1,2 @@ +This is the openai module. + diff --git a/x-pack/metricbeat/module/openai/_meta/fields.yml b/x-pack/metricbeat/module/openai/_meta/fields.yml new file mode 100644 index 000000000000..d514eb010f15 --- /dev/null +++ b/x-pack/metricbeat/module/openai/_meta/fields.yml @@ -0,0 +1,10 @@ +- key: openai + title: "openai" + release: beta + description: > + openai module + fields: + - name: openai + type: group + description: > + fields: diff --git a/x-pack/metricbeat/module/openai/doc.go b/x-pack/metricbeat/module/openai/doc.go new file mode 100644 index 000000000000..5f2f07fb0bca --- /dev/null +++ b/x-pack/metricbeat/module/openai/doc.go @@ -0,0 +1,6 @@ +// Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one +// or more contributor license agreements. Licensed under the Elastic License; +// you may not use this file except in compliance with the Elastic License. + +// Package openai is a Metricbeat module that contains MetricSets. +package openai diff --git a/x-pack/metricbeat/module/openai/fields.go b/x-pack/metricbeat/module/openai/fields.go new file mode 100644 index 000000000000..de875dbdaab1 --- /dev/null +++ b/x-pack/metricbeat/module/openai/fields.go @@ -0,0 +1,23 @@ +// Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one +// or more contributor license agreements. Licensed under the Elastic License; +// you may not use this file except in compliance with the Elastic License. + +// Code generated by beats/dev-tools/cmd/asset/asset.go - DO NOT EDIT. + +package openai + +import ( + "github.com/elastic/beats/v7/libbeat/asset" +) + +func init() { + if err := asset.SetFields("metricbeat", "openai", asset.ModuleFieldsPri, AssetOpenai); err != nil { + panic(err) + } +} + +// AssetOpenai returns asset data. +// This is the base64 encoded zlib format compressed contents of module/openai. +func AssetOpenai() string { + return "eJzsWMtu4zgQvPsrGtnL7sHYuw8BjOwDAbKbIMlgjgIttmWOKVJDtuI4Xz+gJNp6UHZsyRMEGB5FsqpZrK6YmcIatzPQGSomJgAkSOIMrsoPVxMAgxKZxRkskNgEgKONjchIaDWD6wkAVLsh1TyXOAFYCpTczoq5KSiWYo3BDdpmOIPE6DyrvgRQmzh1rNyyBHdfQ3ButAv3I0hVjvsM1fwW5g+3JQekSEbEFpjiYImRsCRiW9vTLtGN3+BGp6lWsGAWqxXACIzWBBJfUDaW7xQyCVPijbnCIsEba/wZ17jdaNOea5zovgYDgqMisRRojlO6T6OQdoA8HctEtMbtgMO5m1nj9ti5PNGQI3mqo6cxyFlMePaZHqv9nvEgmUM9l+h5myHo5UGezOhvGNOAK3ooEY5dkScackWeqoHRbcVMolv/582KUdXXnDUiYV9WZ6IvXTrFXLcmAf5FhYbJGqXPk9bSUIjUizL4PUdLNiJNTHaW+RKlVklgslHl/3m6QONc4EEhZbx9A43YNkVX97KG76lDfO+BIGDhPZ9VLLMrHTDgyYxPFVSfE+u0sVaErxSRXqMaQ+dnhwBqp3ZFACUB5LaTF/tiksI3hPxy5ewoqoL6hWHxCnl0eX0KnpZMvVVhykQ//zv98cWi6UFqNV4odU+m8+lbYfbl1V/zu7vp3yBSlxnVNbmuCSXHPrSkDIfoGalVFdD5DXRiZqk8jYpDdG/xvLwqwfbO/Zi07GUtyouseBtslCfxhs0e7dHxozI6t2hGyOei/96RzanmKEfg+8/hhAhbHfh1JWyGBmyGGK+mpKdFJB1qwE25ZawW9BUM7cGLK9cmdE1vMdaKj9X1FZr7uRijPfRX82Pa/sK90LLmM76SM+RTYc2DlqRO0WfbscX6KV0Zr5hxrywzljH3gL+8WXhzzrlwG5gsnzqOw8Lvhm3AkjYswT+CRl1SNOaj6x+hcEq5EioZ8uTSRiRCHbgrvXBPz8B0ORGdJPEj28CyVXhY593/A6wVlpiiKNYcI6EITWaQxvsjNPcMcKM5wu2eYVD3/3xhd1KBkwpqUr1DZ+MOiS9MRpWJx5L30QP77vhkqppO/YWYPwIAAP//Z/rS7Q==" +} diff --git a/x-pack/metricbeat/module/openai/usage/_meta/data.json b/x-pack/metricbeat/module/openai/usage/_meta/data.json new file mode 100644 index 000000000000..da78c73e036f --- /dev/null +++ b/x-pack/metricbeat/module/openai/usage/_meta/data.json @@ -0,0 +1,37 @@ +{ + "@timestamp": "2017-10-12T08:05:34.853Z", + "event": { + "dataset": "openai.usage", + "duration": 115000, + "module": "openai" + }, + "metricset": { + "name": "usage", + "period": 10000 + }, + "openai": { + "usage": { + "api_key_id": null, + "api_key_name": null, + "api_key_redacted": null, + "api_key_type": null, + "data": { + "cached_context_tokens_total": 0, + "context_tokens_total": 118, + "email": null, + "generated_tokens_total": 35, + "operation": "completion-realtime", + "request_type": "", + "requests_total": 1, + "snapshot_id": "gpt-4o-realtime-preview-2024-10-01" + }, + "organization_id": "org-dummy", + "organization_name": "Personal", + "project_id": null, + "project_name": null + } + }, + "service": { + "type": "openai" + } +} \ No newline at end of file diff --git a/x-pack/metricbeat/module/openai/usage/_meta/docs.asciidoc b/x-pack/metricbeat/module/openai/usage/_meta/docs.asciidoc new file mode 100644 index 000000000000..dc88baf82a09 --- /dev/null +++ b/x-pack/metricbeat/module/openai/usage/_meta/docs.asciidoc @@ -0,0 +1 @@ +This is the usage metricset of the module openai. diff --git a/x-pack/metricbeat/module/openai/usage/_meta/fields.yml b/x-pack/metricbeat/module/openai/usage/_meta/fields.yml new file mode 100644 index 000000000000..c25fe30c17bb --- /dev/null +++ b/x-pack/metricbeat/module/openai/usage/_meta/fields.yml @@ -0,0 +1,156 @@ +- name: usage + type: group + release: beta + description: > + OpenAI API usage metrics and statistics + fields: + # Common base fields at root level + - name: organization_id + type: keyword + description: Organization identifier + - name: organization_name + type: keyword + description: Organization name + - name: api_key_id + type: keyword + description: API key identifier + - name: api_key_name + type: keyword + description: API key name + - name: api_key_redacted + type: keyword + description: Redacted API key + - name: api_key_type + type: keyword + description: Type of API key + - name: project_id + type: keyword + description: Project identifier + - name: project_name + type: keyword + description: Project name + + # Completion/Chat usage data + - name: data + type: group + description: > + General usage data metrics + fields: + - name: requests_total + type: long + description: Number of requests made + - name: operation + type: keyword + description: Operation type + - name: snapshot_id + type: keyword + description: Snapshot identifier + - name: context_tokens_total + type: long + description: Total number of context tokens used + - name: generated_tokens_total + type: long + description: Total number of generated tokens + - name: cached_context_tokens_total + type: long + description: Total number of cached context tokens + - name: email + type: keyword + description: User email + - name: request_type + type: keyword + description: Type of request + + # DALL-E image generation metrics + - name: dalle + type: group + description: > + DALL-E API usage metrics + fields: + - name: num_images + type: long + description: Number of images generated + - name: requests_total + type: long + description: Number of requests + - name: image_size + type: keyword + description: Size of generated images + - name: operation + type: keyword + description: Operation type + - name: user_id + type: keyword + description: User identifier + - name: model_id + type: keyword + description: Model identifier + + # Whisper speech-to-text metrics + - name: whisper + type: group + description: > + Whisper API usage metrics + fields: + - name: model_id + type: keyword + description: Model identifier + - name: num_seconds + type: long + description: Number of seconds processed + - name: requests_total + type: long + description: Number of requests + - name: user_id + type: keyword + description: User identifier + + # Text-to-Speech metrics + - name: tts + type: group + description: > + Text-to-Speech API usage metrics + fields: + - name: model_id + type: keyword + description: Model identifier + - name: num_characters + type: long + description: Number of characters processed + - name: requests_total + type: long + description: Number of requests + - name: user_id + type: keyword + description: User identifier + + # Additional data types (raw storage) + - name: ft_data + type: group + description: > + Fine-tuning data metrics + fields: + - name: original + type: object + object_type: keyword + description: Raw fine-tuning data + + - name: assistant_code_interpreter + type: group + description: > + Assistant Code Interpreter usage metrics + fields: + - name: original + type: object + object_type: keyword + description: Raw assistant code interpreter data + + - name: retrieval_storage + type: group + description: > + Retrieval storage usage metrics + fields: + - name: original + type: object + object_type: keyword + description: Raw retrieval storage data diff --git a/x-pack/metricbeat/module/openai/usage/client.go b/x-pack/metricbeat/module/openai/usage/client.go new file mode 100644 index 000000000000..3995386c30e7 --- /dev/null +++ b/x-pack/metricbeat/module/openai/usage/client.go @@ -0,0 +1,71 @@ +// Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one +// or more contributor license agreements. Licensed under the Elastic License; +// you may not use this file except in compliance with the Elastic License. + +package usage + +import ( + "fmt" + "net/http" + "time" + + "golang.org/x/time/rate" + + "github.com/elastic/elastic-agent-libs/logp" +) + +// RLHTTPClient wraps the standard http.Client with a rate limiter to control API request frequency. +type RLHTTPClient struct { + client *http.Client + logger *logp.Logger + Ratelimiter *rate.Limiter +} + +// Do executes an HTTP request while respecting rate limits. +// It waits for rate limit token before proceeding with the request. +// Returns the HTTP response and any error encountered. +func (c *RLHTTPClient) Do(req *http.Request) (*http.Response, error) { + start := time.Now() + + c.logger.Debug("Waiting for rate limit token") + + err := c.Ratelimiter.Wait(req.Context()) + if err != nil { + return nil, fmt.Errorf("failed to acquire rate limit token: %w", err) + } + + c.logger.Debug("Rate limit token acquired") + + waitDuration := time.Since(start) + + if waitDuration > time.Minute { + c.logger.Infof("Rate limit wait exceeded threshold: %v", waitDuration) + } + + resp, err := c.client.Do(req) + if err != nil { + return nil, fmt.Errorf("failed to execute request: %w", err) + } + + return resp, nil +} + +// newClient creates a new rate-limited HTTP client with specified rate limiter and timeout. +func newClient(logger *logp.Logger, rl *rate.Limiter, timeout time.Duration) *RLHTTPClient { + transport := &http.Transport{ + MaxIdleConns: 100, + MaxIdleConnsPerHost: 100, + IdleConnTimeout: 90 * time.Second, + } + + client := &http.Client{ + Timeout: timeout, + Transport: transport, + } + + return &RLHTTPClient{ + client: client, + logger: logger, + Ratelimiter: rl, + } +} diff --git a/x-pack/metricbeat/module/openai/usage/config.go b/x-pack/metricbeat/module/openai/usage/config.go new file mode 100644 index 000000000000..f930a0137476 --- /dev/null +++ b/x-pack/metricbeat/module/openai/usage/config.go @@ -0,0 +1,94 @@ +// Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one +// or more contributor license agreements. Licensed under the Elastic License; +// you may not use this file except in compliance with the Elastic License. + +package usage + +import ( + "errors" + "fmt" + "net/url" + "time" +) + +type Config struct { + APIKeys []apiKeyConfig `config:"api_keys" validate:"required"` + APIURL string `config:"api_url" validate:"required"` + Headers []string `config:"headers"` + RateLimit *rateLimitConfig `config:"rate_limit"` + Timeout time.Duration `config:"timeout" validate:"required"` + Collection collectionConfig `config:"collection"` +} + +type rateLimitConfig struct { + Limit *int `config:"limit" validate:"required"` + Burst *int `config:"burst" validate:"required"` +} + +type apiKeyConfig struct { + Key string `config:"key" validate:"required"` +} + +type collectionConfig struct { + LookbackDays int `config:"lookback_days"` + Realtime bool `config:"realtime"` +} + +func defaultConfig() Config { + return Config{ + APIURL: "https://api.openai.com/v1/usage", + Timeout: 30 * time.Second, + RateLimit: &rateLimitConfig{ + Limit: ptr(12), + Burst: ptr(1), + }, + Collection: collectionConfig{ + LookbackDays: 0, // 0 days + Realtime: false, // avoid realtime collection by default + }, + } +} + +func (c *Config) Validate() error { + var errs []error + + if len(c.APIKeys) == 0 { + errs = append(errs, errors.New("at least one API key must be configured")) + } + if c.APIURL == "" { + errs = append(errs, errors.New("api_url cannot be empty")) + } else { + _, err := url.ParseRequestURI(c.APIURL) + if err != nil { + errs = append(errs, fmt.Errorf("invalid api_url format: %w", err)) + } + } + if c.RateLimit == nil { + errs = append(errs, errors.New("rate_limit must be configured")) + } else { + if c.RateLimit.Limit == nil { + errs = append(errs, errors.New("rate_limit.limit must be configured")) + } + if c.RateLimit.Burst == nil { + errs = append(errs, errors.New("rate_limit.burst must be configured")) + } + } + if c.Timeout <= 0 { + errs = append(errs, errors.New("timeout must be greater than 0")) + } + if c.Collection.LookbackDays < 0 { + errs = append(errs, errors.New("lookback_days must be >= 0")) + } + + for i, apiKey := range c.APIKeys { + if apiKey.Key == "" { + errs = append(errs, fmt.Errorf("API key at position %d cannot be empty", i)) + } + } + + if len(errs) > 0 { + return fmt.Errorf("validation failed: %w", errors.Join(errs...)) + } + + return nil +} diff --git a/x-pack/metricbeat/module/openai/usage/errors.go b/x-pack/metricbeat/module/openai/usage/errors.go new file mode 100644 index 000000000000..9b8b793767c0 --- /dev/null +++ b/x-pack/metricbeat/module/openai/usage/errors.go @@ -0,0 +1,10 @@ +// Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one +// or more contributor license agreements. Licensed under the Elastic License; +// you may not use this file except in compliance with the Elastic License. + +package usage + +import "errors" + +// ErrNoState indicates no previous state exists for the given API key +var ErrNoState = errors.New("no previous state found") diff --git a/x-pack/metricbeat/module/openai/usage/helper.go b/x-pack/metricbeat/module/openai/usage/helper.go new file mode 100644 index 000000000000..992c025df8cc --- /dev/null +++ b/x-pack/metricbeat/module/openai/usage/helper.go @@ -0,0 +1,30 @@ +// Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one +// or more contributor license agreements. Licensed under the Elastic License; +// you may not use this file except in compliance with the Elastic License. + +package usage + +import "strings" + +// dateFormatForStateStore is used to parse and format dates in the YYYY-MM-DD format +const dateFormatForStateStore = "2006-01-02" + +func ptr[T any](value T) *T { + return &value +} + +func processHeaders(headers []string) map[string]string { + headersMap := make(map[string]string, len(headers)) + for _, header := range headers { + parts := strings.SplitN(header, ":", 2) + if len(parts) != 2 { + continue + } + k, v := strings.TrimSpace(parts[0]), strings.TrimSpace(parts[1]) + if k == "" || v == "" { + continue + } + headersMap[k] = v + } + return headersMap +} diff --git a/x-pack/metricbeat/module/openai/usage/persistcache.go b/x-pack/metricbeat/module/openai/usage/persistcache.go new file mode 100644 index 000000000000..51a8d6fb0f89 --- /dev/null +++ b/x-pack/metricbeat/module/openai/usage/persistcache.go @@ -0,0 +1,187 @@ +// Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one +// or more contributor license agreements. Licensed under the Elastic License; +// you may not use this file except in compliance with the Elastic License. + +package usage + +import ( + "crypto/sha256" + "encoding/hex" + "errors" + "fmt" + "os" + "path" + "strings" + "sync" + "time" +) + +// stateManager handles the storage and retrieval of state data with key hashing and caching capabilities +type stateManager struct { + mu sync.RWMutex + store *stateStore + keyPrefix string + hashCache sync.Map +} + +// stateStore handles persistence of key-value pairs using the filesystem +type stateStore struct { + Dir string // Base directory for storing state files + mu sync.RWMutex +} + +// newStateManager creates a new state manager instance with the given storage path +func newStateManager(storePath string) (*stateManager, error) { + if strings.TrimSpace(storePath) == "" { + return nil, errors.New("empty path provided") + } + + store, err := newStateStore(storePath) + if err != nil { + return nil, fmt.Errorf("create state store: %w", err) + } + + return &stateManager{ + mu: sync.RWMutex{}, + store: store, + keyPrefix: "state_", + hashCache: sync.Map{}, + }, nil +} + +// newStateStore creates a new state store instance at the specified path +func newStateStore(path string) (*stateStore, error) { + if err := os.MkdirAll(path, 0o755); err != nil { + return nil, fmt.Errorf("creating state directory: %w", err) + } + return &stateStore{ + Dir: path, + }, nil +} + +// getStatePath builds the full file path for a given state key +func (s *stateStore) getStatePath(name string) string { + return path.Join(s.Dir, name) +} + +// Put stores a value in a file named by the key +func (s *stateStore) Put(key, value string) error { + s.mu.Lock() + defer s.mu.Unlock() + + filePath := s.getStatePath(key) + + // In case the file already exists, file is truncated. + f, err := os.Create(filePath) + if err != nil { + return fmt.Errorf("creating state file: %w", err) + } + defer f.Close() + + _, err = f.WriteString(value) + if err != nil { + return fmt.Errorf("writing value to state file: %w", err) + } + + if err = f.Sync(); err != nil { + return fmt.Errorf("syncing state file: %w", err) + } + + return nil +} + +// Get retrieves the value stored in the file named by the key +func (s *stateStore) Get(key string) (string, error) { + s.mu.RLock() + defer s.mu.RUnlock() + + filePath := s.getStatePath(key) + data, err := os.ReadFile(filePath) + if err != nil { + return "", fmt.Errorf("reading state file: %w", err) + } + return string(data), nil +} + +// Has checks if a state exists for the given key +func (s *stateStore) Has(key string) bool { + s.mu.RLock() + defer s.mu.RUnlock() + + filePath := s.getStatePath(key) + _, err := os.Stat(filePath) + return err == nil +} + +// Remove deletes the state file for the given key +func (s *stateStore) Remove(key string) error { + s.mu.Lock() + defer s.mu.Unlock() + + filePath := s.getStatePath(key) + if err := os.Remove(filePath); err != nil && !os.IsNotExist(err) { + return fmt.Errorf("removing state file: %w", err) + } + return nil +} + +// Clear removes all state files by deleting and recreating the state directory +func (s *stateStore) Clear() error { + s.mu.Lock() + defer s.mu.Unlock() + + if err := os.RemoveAll(s.Dir); err != nil { + return fmt.Errorf("clearing state directory: %w", err) + } + return os.MkdirAll(s.Dir, 0o755) +} + +// GetLastProcessedDate retrieves and parses the last processed date for a given API key +func (s *stateManager) GetLastProcessedDate(apiKey string) (time.Time, error) { + s.mu.RLock() + defer s.mu.RUnlock() + + stateKey := s.GetStateKey(apiKey) + + if !s.store.Has(stateKey) { + return time.Time{}, ErrNoState + } + + dateStr, err := s.store.Get(stateKey) + if err != nil { + return time.Time{}, fmt.Errorf("get state: %w", err) + } + + return time.Parse(dateFormatForStateStore, dateStr) +} + +// SaveState saves the last processed date for a given API key +func (s *stateManager) SaveState(apiKey, dateStr string) error { + s.mu.Lock() + defer s.mu.Unlock() + + stateKey := s.GetStateKey(apiKey) + return s.store.Put(stateKey, dateStr) +} + +// hashKey generates and caches a SHA-256 hash of the provided API key +func (s *stateManager) hashKey(apiKey string) string { + // Check cache first to avoid recomputing hashes + if hashedKey, ok := s.hashCache.Load(apiKey); ok { + return hashedKey.(string) + } + + // Generate SHA-256 hash and hex encode for safe filename usage + hasher := sha256.New() + _, _ = hasher.Write([]byte(apiKey)) + hashedKey := hex.EncodeToString(hasher.Sum(nil)) + + // Cache the computed hash for future lookups + s.hashCache.Store(apiKey, hashedKey) + return hashedKey +} + +// GetStateKey generates a unique state key for a given API key +func (s *stateManager) GetStateKey(apiKey string) string { + return s.keyPrefix + s.hashKey(apiKey) +} diff --git a/x-pack/metricbeat/module/openai/usage/schema.go b/x-pack/metricbeat/module/openai/usage/schema.go new file mode 100644 index 000000000000..64f22393e590 --- /dev/null +++ b/x-pack/metricbeat/module/openai/usage/schema.go @@ -0,0 +1,69 @@ +// Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one +// or more contributor license agreements. Licensed under the Elastic License; +// you may not use this file except in compliance with the Elastic License. + +package usage + +type BaseData struct { + OrganizationID string `json:"organization_id"` + OrganizationName string `json:"organization_name"` + ApiKeyID *string `json:"api_key_id"` + ApiKeyName *string `json:"api_key_name"` + ApiKeyRedacted *string `json:"api_key_redacted"` + ApiKeyType *string `json:"api_key_type"` + ProjectID *string `json:"project_id"` + ProjectName *string `json:"project_name"` +} + +type UsageResponse struct { + Object string `json:"object"` + Data []UsageData `json:"data"` + FtData []interface{} `json:"ft_data"` + DalleApiData []DalleData `json:"dalle_api_data"` + WhisperApiData []WhisperData `json:"whisper_api_data"` + TtsApiData []TtsData `json:"tts_api_data"` + AssistantCodeInterpreterData []interface{} `json:"assistant_code_interpreter_data"` + RetrievalStorageData []interface{} `json:"retrieval_storage_data"` +} + +type UsageData struct { + BaseData + AggregationTimestamp int64 `json:"aggregation_timestamp"` + NRequests int `json:"n_requests"` + Operation string `json:"operation"` + SnapshotID string `json:"snapshot_id"` + NContextTokensTotal int `json:"n_context_tokens_total"` + NGeneratedTokensTotal int `json:"n_generated_tokens_total"` + Email *string `json:"email"` + RequestType string `json:"request_type"` + NCachedContextTokensTotal int `json:"n_cached_context_tokens_total"` +} + +type DalleData struct { + BaseData + Timestamp int64 `json:"timestamp"` + NumImages int `json:"num_images"` + NumRequests int `json:"num_requests"` + ImageSize string `json:"image_size"` + Operation string `json:"operation"` + ModelID string `json:"model_id"` + UserID string `json:"user_id"` +} + +type WhisperData struct { + BaseData + Timestamp int64 `json:"timestamp"` + ModelID string `json:"model_id"` + NumSeconds int `json:"num_seconds"` + NumRequests int `json:"num_requests"` + UserID string `json:"user_id"` +} + +type TtsData struct { + BaseData + Timestamp int64 `json:"timestamp"` + ModelID string `json:"model_id"` + NumCharacters int `json:"num_characters"` + NumRequests int `json:"num_requests"` + UserID string `json:"user_id"` +} diff --git a/x-pack/metricbeat/module/openai/usage/usage.go b/x-pack/metricbeat/module/openai/usage/usage.go new file mode 100644 index 000000000000..86dbe76ce815 --- /dev/null +++ b/x-pack/metricbeat/module/openai/usage/usage.go @@ -0,0 +1,387 @@ +// Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one +// or more contributor license agreements. Licensed under the Elastic License; +// you may not use this file except in compliance with the Elastic License. + +package usage + +import ( + "context" + "encoding/json" + "errors" + "fmt" + "net" + "net/http" + "path" + "time" + + "golang.org/x/sync/errgroup" + "golang.org/x/time/rate" + + "github.com/elastic/beats/v7/libbeat/common/cfgwarn" + "github.com/elastic/beats/v7/metricbeat/mb" + "github.com/elastic/elastic-agent-libs/logp" + "github.com/elastic/elastic-agent-libs/mapstr" + "github.com/elastic/elastic-agent-libs/paths" +) + +// init registers the MetricSet with the central registry as soon as the program +// starts. The New function will be called later to instantiate an instance of +// the MetricSet for each host is defined in the module's configuration. After the +// MetricSet has been created then Fetch will begin to be called periodically. +func init() { + mb.Registry.MustAddMetricSet("openai", "usage", New) +} + +// MetricSet holds any configuration or state information. It must implement +// the mb.MetricSet interface. And this is best achieved by embedding +// mb.BaseMetricSet because it implements all of the required mb.MetricSet +// interface methods except for Fetch. +type MetricSet struct { + mb.BaseMetricSet + httpClient *RLHTTPClient + logger *logp.Logger + config Config + report mb.ReporterV2 + stateManager *stateManager + headers map[string]string +} + +// New creates a new instance of the MetricSet. New is responsible for unpacking +// any MetricSet specific configuration options if there are any. +func New(base mb.BaseMetricSet) (mb.MetricSet, error) { + cfgwarn.Beta("The openai usage metricset is beta.") + + config := defaultConfig() + if err := base.Module().UnpackConfig(&config); err != nil { + return nil, err + } + + if err := config.Validate(); err != nil { + return nil, err + } + + sm, err := newStateManager(paths.Resolve(paths.Data, path.Join("state", base.Module().Name(), base.Name()))) + if err != nil { + return nil, fmt.Errorf("create state manager: %w", err) + } + + logger := logp.NewLogger("openai.usage") + + httpClient := newClient( + logger, + rate.NewLimiter( + rate.Every(time.Duration(*config.RateLimit.Limit)*time.Second), + *config.RateLimit.Burst, + ), + config.Timeout, + ) + + return &MetricSet{ + BaseMetricSet: base, + httpClient: httpClient, + logger: logger, + config: config, + stateManager: sm, + headers: processHeaders(config.Headers), + }, nil +} + +// Fetch collects OpenAI API usage data for the configured time range. +// +// The collection process: +// 1. Determines the time range based on realtime/non-realtime configuration +// 2. Calculates start date using configured lookback days +// 3. Fetches usage data for each day in the range +// 4. Reports collected metrics through the mb.ReporterV2 +func (m *MetricSet) Fetch(report mb.ReporterV2) error { + endDate := time.Now().UTC().Truncate(time.Hour * 24) // truncate to day as we only collect daily data + + if !m.config.Collection.Realtime { + // If we're not collecting realtime data, then just pull until + // yesterday (in UTC). + endDate = endDate.AddDate(0, 0, -1) + } + + startDate := endDate.AddDate(0, 0, -m.config.Collection.LookbackDays) + + m.report = report + return m.fetchDateRange(startDate, endDate, m.httpClient) +} + +// fetchDateRange retrieves OpenAI API usage data for each configured API key within a date range. +// +// For each API key: +// 1. Retrieves last processed date from state store +// 2. Adjusts collection range to avoid duplicates +// 3. Collects daily usage data +// 4. Updates state store with latest processed date +// 5. Handles errors per day without failing entire range +func (m *MetricSet) fetchDateRange(startDate, endDate time.Time, httpClient *RLHTTPClient) error { + g, ctx := errgroup.WithContext(context.TODO()) + + for i := range m.config.APIKeys { + apiKey := m.config.APIKeys[i] + apiKeyIdx := i + 1 + g.Go(func() error { + lastProcessedDate, err := m.stateManager.GetLastProcessedDate(apiKey.Key) + if err == nil { + currentStartDate := lastProcessedDate.AddDate(0, 0, 1) + if currentStartDate.After(endDate) { + m.logger.Infof("Skipping API key #%d as current start date (%s) is after end date (%s)", apiKeyIdx, currentStartDate, endDate) + return nil + } + startDate = currentStartDate + } + + m.logger.Debugf("Fetching data for API key #%d from %s to %s", apiKeyIdx, startDate, endDate) + + for d := startDate; !d.After(endDate); d = d.AddDate(0, 0, 1) { + select { + case <-ctx.Done(): + return ctx.Err() + default: + dateStr := d.Format(dateFormatForStateStore) + if err := m.fetchSingleDay(apiKeyIdx, dateStr, apiKey.Key, httpClient); err != nil { + // If there's an error, log it and continue to the next day. + // In this case, we are not saving the state. + m.logger.Errorf("Error fetching data (api key #%d) for date %s: %v", apiKeyIdx, dateStr, err) + continue + } + if err := m.stateManager.SaveState(apiKey.Key, dateStr); err != nil { + m.logger.Errorf("Error storing state for API key: %v at index %d", err, apiKeyIdx) + } + } + } + return nil + }) + } + + if err := g.Wait(); err != nil { + m.logger.Errorf("Error fetching data: %v", err) + } + + return nil +} + +// fetchSingleDay retrieves usage data for a specific date and API key. +func (m *MetricSet) fetchSingleDay(apiKeyIdx int, dateStr, apiKey string, httpClient *RLHTTPClient) error { + req, err := m.createRequest(dateStr, apiKey) + if err != nil { + return fmt.Errorf("error creating request: %w", err) + } + + resp, err := httpClient.Do(req) + if err != nil { + var netErr net.Error + if errors.As(err, &netErr) && netErr.Timeout() { + return fmt.Errorf("request timed out with configured timeout: %v and error: %w", m.config.Timeout, err) + } + return fmt.Errorf("error making request: %w", err) + } + defer resp.Body.Close() + + if resp.StatusCode != http.StatusOK { + return fmt.Errorf("error response from API: status=%s", resp.Status) + } + + return m.processResponse(apiKeyIdx, resp, dateStr) +} + +// createRequest builds an HTTP request for the OpenAI usage API. +func (m *MetricSet) createRequest(dateStr, apiKey string) (*http.Request, error) { + req, err := http.NewRequestWithContext(context.TODO(), http.MethodGet, m.config.APIURL, nil) + if err != nil { + return nil, fmt.Errorf("error creating request: %w", err) + } + + q := req.URL.Query() + q.Add("date", dateStr) + req.URL.RawQuery = q.Encode() + + req.Header.Add("Authorization", fmt.Sprintf("Bearer %s", apiKey)) + for key, value := range m.headers { + req.Header.Add(key, value) + } + + return req, nil +} + +// processResponse handles the API response and processes the usage data. +func (m *MetricSet) processResponse(apiKeyIdx int, resp *http.Response, dateStr string) error { + var usageResponse UsageResponse + if err := json.NewDecoder(resp.Body).Decode(&usageResponse); err != nil { + return fmt.Errorf("error decoding response: %w", err) + } + + m.logger.Infof("Fetching usage metrics (api key #%d) for date: %s", apiKeyIdx, dateStr) + + m.processUsageData(usageResponse.Data) + m.processDalleData(usageResponse.DalleApiData) + m.processWhisperData(usageResponse.WhisperApiData) + m.processTTSData(usageResponse.TtsApiData) + + // Process additional data. + // + // NOTE(shmsr): During testing, could not get the usage data for the following + // and found no documentation, example responses, etc. That's why let's store them + // as it is so that we can use processors later on to process them as needed. + m.processFTData(usageResponse.FtData) + m.processAssistantCodeInterpreterData(usageResponse.AssistantCodeInterpreterData) + m.processRetrievalStorageData(usageResponse.RetrievalStorageData) + + return nil +} + +func getBaseFields(data BaseData) mapstr.M { + return mapstr.M{ + "organization_id": data.OrganizationID, + "organization_name": data.OrganizationName, + "api_key_id": data.ApiKeyID, + "api_key_name": data.ApiKeyName, + "api_key_redacted": data.ApiKeyRedacted, + "api_key_type": data.ApiKeyType, + "project_id": data.ProjectID, + "project_name": data.ProjectName, + } +} + +func (m *MetricSet) processUsageData(data []UsageData) { + events := make([]mb.Event, 0, len(data)) + for _, usage := range data { + event := mb.Event{ + Timestamp: time.Unix(usage.AggregationTimestamp, 0).UTC(), // epoch time to time.Time (UTC) + MetricSetFields: mapstr.M{ + "data": mapstr.M{ + "requests_total": usage.NRequests, + "operation": usage.Operation, + "snapshot_id": usage.SnapshotID, + "context_tokens_total": usage.NContextTokensTotal, + "generated_tokens_total": usage.NGeneratedTokensTotal, + "email": usage.Email, + "request_type": usage.RequestType, + "cached_context_tokens_total": usage.NCachedContextTokensTotal, + }, + }, + } + event.MetricSetFields.DeepUpdate(getBaseFields(usage.BaseData)) + events = append(events, event) + } + m.processEvents(events) +} + +func (m *MetricSet) processDalleData(data []DalleData) { + events := make([]mb.Event, 0, len(data)) + for _, dalle := range data { + event := mb.Event{ + Timestamp: time.Unix(dalle.Timestamp, 0).UTC(), // epoch time to time.Time (UTC) + MetricSetFields: mapstr.M{ + "dalle": mapstr.M{ + "num_images": dalle.NumImages, + "requests_total": dalle.NumRequests, + "image_size": dalle.ImageSize, + "operation": dalle.Operation, + "user_id": dalle.UserID, + "model_id": dalle.ModelID, + }, + }, + } + event.MetricSetFields.DeepUpdate(getBaseFields(dalle.BaseData)) + events = append(events, event) + } + m.processEvents(events) +} + +func (m *MetricSet) processWhisperData(data []WhisperData) { + events := make([]mb.Event, 0, len(data)) + for _, whisper := range data { + event := mb.Event{ + Timestamp: time.Unix(whisper.Timestamp, 0).UTC(), // epoch time to time.Time (UTC) + MetricSetFields: mapstr.M{ + "whisper": mapstr.M{ + "model_id": whisper.ModelID, + "num_seconds": whisper.NumSeconds, + "requests_total": whisper.NumRequests, + "user_id": whisper.UserID, + }, + }, + } + event.MetricSetFields.DeepUpdate(getBaseFields(whisper.BaseData)) + events = append(events, event) + } + m.processEvents(events) +} + +func (m *MetricSet) processTTSData(data []TtsData) { + events := make([]mb.Event, 0, len(data)) + for _, tts := range data { + event := mb.Event{ + Timestamp: time.Unix(tts.Timestamp, 0).UTC(), // epoch time to time.Time (UTC) + MetricSetFields: mapstr.M{ + "tts": mapstr.M{ + "model_id": tts.ModelID, + "num_characters": tts.NumCharacters, + "requests_total": tts.NumRequests, + "user_id": tts.UserID, + }, + }, + } + event.MetricSetFields.DeepUpdate(getBaseFields(tts.BaseData)) + events = append(events, event) + } + + m.processEvents(events) +} + +func (m *MetricSet) processFTData(data []interface{}) { + events := make([]mb.Event, 0, len(data)) + for _, ft := range data { + event := mb.Event{ + MetricSetFields: mapstr.M{ + "ft_data": mapstr.M{ + "original": ft, + }, + }, + } + events = append(events, event) + } + m.processEvents(events) +} + +func (m *MetricSet) processAssistantCodeInterpreterData(data []interface{}) { + events := make([]mb.Event, 0, len(data)) + for _, aci := range data { + event := mb.Event{ + MetricSetFields: mapstr.M{ + "assistant_code_interpreter": mapstr.M{ + "original": aci, + }, + }, + } + events = append(events, event) + } + m.processEvents(events) +} + +func (m *MetricSet) processRetrievalStorageData(data []interface{}) { + events := make([]mb.Event, 0, len(data)) + for _, rs := range data { + event := mb.Event{ + MetricSetFields: mapstr.M{ + "retrieval_storage": mapstr.M{ + "original": rs, + }, + }, + } + events = append(events, event) + } + m.processEvents(events) +} + +func (m *MetricSet) processEvents(events []mb.Event) { + if len(events) == 0 { + return + } + for i := range events { + m.report.Event(events[i]) + } +} diff --git a/x-pack/metricbeat/module/openai/usage/usage_integration_test.go b/x-pack/metricbeat/module/openai/usage/usage_integration_test.go new file mode 100644 index 000000000000..8cb842419955 --- /dev/null +++ b/x-pack/metricbeat/module/openai/usage/usage_integration_test.go @@ -0,0 +1,482 @@ +// Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one +// or more contributor license agreements. Licensed under the Elastic License; +// you may not use this file except in compliance with the Elastic License. + +//go:build integration + +package usage + +import ( + "fmt" + "net/http" + "net/http/httptest" + "testing" + "time" + + "github.com/stretchr/testify/require" + + "github.com/elastic/beats/v7/metricbeat/mb" + mbtest "github.com/elastic/beats/v7/metricbeat/mb/testing" + "github.com/elastic/elastic-agent-libs/mapstr" +) + +func TestFetch(t *testing.T) { + apiKey := time.Now().String() // to generate a unique API key everytime to ignore the stateStore + usagePath := "/usage" + server := initServer(usagePath, apiKey) + defer server.Close() + + tests := []struct { + name string + expected mb.Event + }{ + { + name: "tc: #1", + expected: mb.Event{ + RootFields: nil, + ModuleFields: nil, + MetricSetFields: mapstr.M{ + "api_key_id": (*string)(nil), + "api_key_name": (*string)(nil), + "api_key_redacted": (*string)(nil), + "api_key_type": (*string)(nil), + "data": mapstr.M{ + "email": (*string)(nil), + "cached_context_tokens_total": 0, + "context_tokens_total": 118, + "generated_tokens_total": 35, + "requests_total": 1, + "operation": "completion-realtime", + "request_type": "", + "snapshot_id": "gpt-4o-realtime-preview-2024-10-01", + }, + "organization_id": "org-dummy", + "organization_name": "Personal", + "project_id": (*string)(nil), + "project_name": (*string)(nil), + }, + Index: "", + ID: "", + Namespace: "", + Timestamp: time.Date(2024, time.November, 4, 5, 1, 0, 0, time.UTC), + Error: error(nil), + Host: "", + Service: "", + Took: 0, + Period: 0, + DisableTimeSeries: false, + }, + }, + { + name: "tc: #2", + expected: mb.Event{ + RootFields: nil, + ModuleFields: nil, + MetricSetFields: mapstr.M{ + "api_key_id": (*string)(nil), + "api_key_name": (*string)(nil), + "api_key_redacted": (*string)(nil), + "api_key_type": (*string)(nil), + "data": mapstr.M{ + "email": (*string)(nil), + "cached_context_tokens_total": 0, + "context_tokens_total": 31, + "generated_tokens_total": 12, + "requests_total": 1, + "operation": "completion", + "request_type": "", + "snapshot_id": "gpt-4o-2024-08-06", + }, + "organization_id": "org-dummy", + "organization_name": "Personal", + "project_id": (*string)(nil), + "project_name": (*string)(nil), + }, + Index: "", + ID: "", + Namespace: "", + Timestamp: time.Date(2024, time.November, 4, 5, 1, 0, 0, time.UTC), + Error: error(nil), + Host: "", + Service: "", + Took: 0, + Period: 0, + DisableTimeSeries: false, + }, + }, + { + name: "tc: #3", + expected: mb.Event{ + RootFields: nil, + ModuleFields: nil, + MetricSetFields: mapstr.M{ + "api_key_id": (*string)(nil), + "api_key_name": (*string)(nil), + "api_key_redacted": (*string)(nil), + "api_key_type": (*string)(nil), + "data": mapstr.M{ + "email": (*string)(nil), + "cached_context_tokens_total": 0, + "context_tokens_total": 13, + "generated_tokens_total": 9, + "requests_total": 1, + "operation": "completion", + "request_type": "", + "snapshot_id": "ft:gpt-3.5-turbo-0125:personal:yay-renew:APjjyG8E:ckpt-step-84", + }, + "organization_id": "org-dummy", + "organization_name": "Personal", + "project_id": (*string)(nil), + "project_name": (*string)(nil), + }, + Index: "", + ID: "", + Namespace: "", + Timestamp: time.Date(2024, time.November, 4, 5, 19, 0, 0, time.UTC), + Error: error(nil), + Host: "", + Service: "", + Took: 0, + Period: 0, + DisableTimeSeries: false, + }, + }, + { + name: "tc: #4", + expected: mb.Event{ + RootFields: nil, + ModuleFields: nil, + MetricSetFields: mapstr.M{ + "api_key_id": ptr("key_sha_id_random"), + "api_key_name": ptr("project_key"), + "api_key_redacted": ptr("sk-...zkA"), + "api_key_type": ptr("organization"), + "dalle": mapstr.M{ + "image_size": "1024x1024", + "model_id": "dall-e-3", + "num_images": 1, + "requests_total": 1, + "operation": "generations", + "user_id": "hello-test@elastic.co", + }, + "organization_id": "org-dummy", + "organization_name": "Personal", + "project_id": ptr("Default Project"), + "project_name": ptr("Default Project"), + }, + Index: "", + ID: "", + Namespace: "", + Timestamp: time.Date(2024, time.November, 4, 5, 1, 0, 0, time.UTC), + Error: error(nil), + Host: "", + Service: "", + Took: 0, + Period: 0, + DisableTimeSeries: false, + }, + }, + { + name: "tc: #5", + expected: mb.Event{ + RootFields: nil, + ModuleFields: nil, + MetricSetFields: mapstr.M{ + "api_key_id": (*string)(nil), + "api_key_name": (*string)(nil), + "api_key_redacted": (*string)(nil), + "api_key_type": (*string)(nil), + "whisper": mapstr.M{ + "model_id": "whisper-1", + "requests_total": 1, + "num_seconds": 2, + "user_id": "", + }, + "organization_id": "org-dummy", + "organization_name": "Personal", + "project_id": (*string)(nil), + "project_name": (*string)(nil), + }, + Index: "", + ID: "", + Namespace: "", + Timestamp: time.Date(2024, time.November, 4, 5, 1, 0, 0, time.UTC), + Error: error(nil), + Host: "", + Service: "", + Took: 0, + Period: 0, + DisableTimeSeries: false, + }, + }, + { + name: "tc: #6", + expected: mb.Event{ + RootFields: nil, + ModuleFields: nil, + MetricSetFields: mapstr.M{ + "api_key_id": ptr("key_fake_id"), + "api_key_name": ptr("project_key"), + "api_key_redacted": ptr("sk-...zkA"), + "api_key_type": ptr("organization"), + "tts": mapstr.M{ + "model_id": "tts-1", + "num_characters": 90, + "requests_total": 2, + "user_id": "hello-test@elastic.co", + }, + "organization_id": "org-fake", + "organization_name": "Personal", + "project_id": ptr("Default Project"), + "project_name": ptr("Default Project"), + }, + Index: "", + ID: "", + Namespace: "", + Timestamp: time.Date(2024, time.September, 4, 0, 0, 0, 0, time.UTC), + Error: error(nil), + Host: "", + Service: "", + Took: 0, + Period: 0, + DisableTimeSeries: false, + }, + }, + { + name: "tc: #7", + expected: mb.Event{ + RootFields: nil, + ModuleFields: nil, + MetricSetFields: mapstr.M{ + "api_key_id": ptr("key_fake_id"), + "api_key_name": ptr("fake_key"), + "api_key_redacted": ptr("sk-...FIA"), + "api_key_type": ptr("project"), + "tts": mapstr.M{ + "model_id": "tts-1", + "num_characters": 45, + "requests_total": 1, + "user_id": "hello-test@elastic.co", + }, + "organization_id": "org-fake", + "organization_name": "Personal", + "project_id": ptr("proj_fake_id"), + "project_name": ptr("fake_proj"), + }, + Index: "", + ID: "", + Namespace: "", + Timestamp: time.Date(2024, time.September, 5, 0, 0, 0, 0, time.UTC), + Error: error(nil), + Host: "", + Service: "", + Took: 0, + Period: 0, + DisableTimeSeries: false, + }, + }, + } + + f := mbtest.NewReportingMetricSetV2Error(t, getConfig(server.URL+"/usage", apiKey)) + events, errs := mbtest.ReportingFetchV2Error(f) + + require.Empty(t, errs, "Expected no errors") + require.NotEmpty(t, events, "Expected events to be returned") + require.Equal(t, len(tests), len(events)) + + for i, tt := range tests { + t.Run(tt.name, func(t *testing.T) { + require.Equal(t, tt.expected, events[i]) + }) + } +} + +func TestData(t *testing.T) { + apiKey := time.Now().String() // to generate a unique API key everytime + usagePath := "/usage" + server := initServer(usagePath, apiKey) + defer server.Close() + + f := mbtest.NewReportingMetricSetV2Error(t, getConfig(server.URL+"/usage", apiKey)) + + err := mbtest.WriteEventsReporterV2Error(f, t, "") + require.NoError(t, err, "Writing events should not return an error") +} + +func getConfig(url, apiKey string) map[string]interface{} { + return map[string]interface{}{ + "module": "openai", + "metricsets": []string{"usage"}, + "enabled": true, + "period": "24h", + "api_url": url, + "api_keys": []map[string]interface{}{ + {"key": apiKey}, + }, + "rate_limit": map[string]interface{}{ + "limit": 60, + "burst": 5, + }, + "collection": map[string]interface{}{ + "lookback_days": 0, + "realtime": false, + }, + } +} + +func initServer(endpoint, api_key string) *httptest.Server { + data := []byte(`{ + "object": "list", + "data": [ + { + "organization_id": "org-dummy", + "organization_name": "Personal", + "aggregation_timestamp": 1730696460, + "n_requests": 1, + "operation": "completion-realtime", + "snapshot_id": "gpt-4o-realtime-preview-2024-10-01", + "n_context_tokens_total": 118, + "n_generated_tokens_total": 35, + "email": null, + "api_key_id": null, + "api_key_name": null, + "api_key_redacted": null, + "api_key_type": null, + "project_id": null, + "project_name": null, + "request_type": "", + "n_cached_context_tokens_total": 0 + }, + { + "organization_id": "org-dummy", + "organization_name": "Personal", + "aggregation_timestamp": 1730696460, + "n_requests": 1, + "operation": "completion", + "snapshot_id": "gpt-4o-2024-08-06", + "n_context_tokens_total": 31, + "n_generated_tokens_total": 12, + "email": null, + "api_key_id": null, + "api_key_name": null, + "api_key_redacted": null, + "api_key_type": null, + "project_id": null, + "project_name": null, + "request_type": "", + "n_cached_context_tokens_total": 0 + }, + { + "organization_id": "org-dummy", + "organization_name": "Personal", + "aggregation_timestamp": 1730697540, + "n_requests": 1, + "operation": "completion", + "snapshot_id": "ft:gpt-3.5-turbo-0125:personal:yay-renew:APjjyG8E:ckpt-step-84", + "n_context_tokens_total": 13, + "n_generated_tokens_total": 9, + "email": null, + "api_key_id": null, + "api_key_name": null, + "api_key_redacted": null, + "api_key_type": null, + "project_id": null, + "project_name": null, + "request_type": "", + "n_cached_context_tokens_total": 0 + } + ], + "ft_data": [], + "dalle_api_data": [ + { + "timestamp": 1730696460, + "num_images": 1, + "num_requests": 1, + "image_size": "1024x1024", + "operation": "generations", + "user_id": "hello-test@elastic.co", + "organization_id": "org-dummy", + "api_key_id": "key_sha_id_random", + "api_key_name": "project_key", + "api_key_redacted": "sk-...zkA", + "api_key_type": "organization", + "organization_name": "Personal", + "model_id": "dall-e-3", + "project_id": "Default Project", + "project_name": "Default Project" + } + ], + "whisper_api_data": [ + { + "timestamp": 1730696460, + "model_id": "whisper-1", + "num_seconds": 2, + "num_requests": 1, + "user_id": null, + "organization_id": "org-dummy", + "api_key_id": null, + "api_key_name": null, + "api_key_redacted": null, + "api_key_type": null, + "organization_name": "Personal", + "project_id": null, + "project_name": null + } + ], + "tts_api_data": [ + { + "timestamp": 1725408000, + "model_id": "tts-1", + "num_characters": 90, + "num_requests": 2, + "user_id": "hello-test@elastic.co", + "organization_id": "org-fake", + "api_key_id": "key_fake_id", + "api_key_name": "project_key", + "api_key_redacted": "sk-...zkA", + "api_key_type": "organization", + "organization_name": "Personal", + "project_id": "Default Project", + "project_name": "Default Project" + }, + { + "timestamp": 1725494400, + "model_id": "tts-1", + "num_characters": 45, + "num_requests": 1, + "user_id": "hello-test@elastic.co", + "organization_id": "org-fake", + "api_key_id": "key_fake_id", + "api_key_name": "fake_key", + "api_key_redacted": "sk-...FIA", + "api_key_type": "project", + "organization_name": "Personal", + "project_id": "proj_fake_id", + "project_name": "fake_proj" + } + ], + "assistant_code_interpreter_data": [], + "retrieval_storage_data": [] +}`) + + server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { + // Validate Bearer token + authHeader := r.Header.Get("Authorization") + expectedToken := fmt.Sprintf("Bearer %s", api_key) + + if authHeader != expectedToken { + w.WriteHeader(http.StatusUnauthorized) + return + } + + // If it doesn't match the expected endpoint, return 404 + if r.URL.Path != endpoint { + w.WriteHeader(http.StatusNotFound) + return + } + + w.WriteHeader(http.StatusOK) + _, _ = w.Write(data) + })) + return server +} diff --git a/x-pack/metricbeat/modules.d/openai.yml.disabled b/x-pack/metricbeat/modules.d/openai.yml.disabled new file mode 100644 index 000000000000..6a881ae86419 --- /dev/null +++ b/x-pack/metricbeat/modules.d/openai.yml.disabled @@ -0,0 +1,37 @@ +# Module: openai +# Docs: https://www.elastic.co/guide/en/beats/metricbeat/main/metricbeat-module-openai.html + +- module: openai + metricsets: ["usage"] + enabled: false + period: 1h + + # # Project API Keys - Multiple API keys can be specified for different projects + # api_keys: + # - key: "api_key1" + # - key: "api_key2" + + # # API Configuration + # ## Base URL for the OpenAI usage API endpoint + # api_url: "https://api.openai.com/v1/usage" + # ## Custom headers to be included in API requests + # headers: + # - "k1: v1" + # - "k2: v2" + ## Rate Limiting Configuration + # rate_limit: + # limit: 12 # seconds between requests + # burst: 1 # max concurrent requests + # ## Request Timeout Duration + # timeout: 30s + + # # Data Collection Configuration + # collection: + # ## Number of days to look back when collecting usage data + # lookback_days: 30 + # ## Whether to collect usage data in realtime. Defaults to false as how + # # OpenAI usage data is collected will end up adding duplicate data to ES + # # and also making it harder to do analytics. Best approach is to avoid + # # realtime collection and collect only upto last day (in UTC). So, there's + # # at most 24h delay. + # realtime: false

^V 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�`i!E9*1c@^*LW4WjYXMc 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