github.com/Jeffail/benthos/v3@v3.65.0/website/docs/guides/migration/v3.md (about)

     1  ---
     2  title: Migrating to Version 3
     3  ---
     4  
     5  Benthos version 3 comes with some breaking [service](#service) and [configuration](#configuration) changes as well as a few breaking [API changes](#go-api).
     6  
     7  ## Service
     8  
     9  ### Memory Map File Buffer Removed
    10  
    11  The long deprecated `mmap_file` buffer has been removed. If you were still relying on this buffer implementation then please [raise an issue](https://github.com/Jeffail/benthos/issues).
    12  
    13  ### Old Metrics Paths Removed
    14  
    15  The following undocumented metrics paths have been removed:
    16  
    17  - `input.parts.count`
    18  - `input.read.success`
    19  - `input.read.error`
    20  - `input.send.success`
    21  - `input.send.error`
    22  - `input.ack.success`
    23  - `input.ack.error`
    24  - `output.running`
    25  - `output.parts.count`
    26  - `output.send.success`
    27  - `output.parts.send.success`
    28  - `output.send.error`
    29  
    30  All of these paths have [remaining equivalents](/docs/components/metrics/about#paths).
    31  
    32  ### Metric Path Changes
    33  
    34  The `http_client` output client metrics have been renamed from `output.*.output.http_client` to `output.*.client`.
    35  
    36  ## Configuration
    37  
    38  ### Metrics Prefix
    39  
    40  The configuration field `prefix` within `metrics` has been moved from the root
    41  of the config object to individual types. E.g. when using `statsd` the field
    42  `metrics.prefix` should be replaced with `metrics.statsd.prefix`.
    43  
    44  ### JSON Paths
    45  
    46  Many components within Benthos use an unspecified "JSON dot path" syntax for querying and setting fields within JSON documents. The format of these paths has been formalised to make them clearer and more generally useful, but this potentially breaks your paths when they query against hierarchies that contain arrays.
    47  
    48  The formal specification for v3 can be found [in this document](/docs/configuration/field_paths).
    49  
    50  The following components are affected:
    51  
    52  - `awk` processor (all of the `json_*` functions)
    53  - `json` processor (`path` field)
    54  - `process_field` processor (`path` field)
    55  - `process_map` processor (`premap`, `premap_optional`, `postmap` and `postmap_optional` fields)
    56  - `check_field` condition (`path` field)
    57  - `json_field` function interpolation
    58  - `s3` input (`sqs_body_path`, `sqs_bucket_path` and `sqs_envelope_path` fields)
    59  - `dynamodb` output (`json_map_columns` field values)
    60  
    61  #### Migration Guide
    62  
    63  In order to replicate the exact same behaviour as currently exists your paths should be updated to include the character `*` wherever an array exists. For example, the default value of `sqs_body_path` for the `s3` input has been updated from `Records.s3.object.key` to `Records.*.s3.object.key`.
    64  
    65  ### Process DAG Stage Names
    66  
    67  The `process_dag` processor now only permits workflow stage names matching the following regular expression: `[a-zA-Z0-9_-]+`. The reasoning for this restriction is to potentially expand the features of `process_dag` in the future with custom root fields (e.g. `$on_error`).
    68  
    69  ## Go API
    70  
    71  ### Modules
    72  
    73  Benthos now fully adheres to [Go Modules](https://github.com/golang/go/wiki/Modules), import paths must therefore now contain the major version (v3) like so:
    74  
    75  ```go
    76  import "github.com/Jeffail/benthos/v3/lib/processor"
    77  ```
    78  
    79  It should be pretty quick to update your imports, either using a tool or just:
    80  
    81  ```sh
    82  grep "Jeffail/benthos" . -Rl | grep -e "\.go$" | xargs -I{} sed -i 's/Jeffail\/benthos/Jeffail\/benthos\/v3/g' {}
    83  ```
    84  
    85  ### Other
    86  
    87  - Constructors for buffer components now require a `types.Manager`, giving them parity with other components: `buffer.New(conf Config, mgr types.Manager, log log.Modular, stats metrics.Type) (Type, error)`