Skip to content

Commit

Permalink
Merge branch 'main' into deprecate-checkreceivertraces
Browse files Browse the repository at this point in the history
  • Loading branch information
sincejune authored Feb 4, 2025
2 parents c9bac7b + 1041a0b commit 72f29d1
Show file tree
Hide file tree
Showing 13 changed files with 46 additions and 44 deletions.
2 changes: 2 additions & 0 deletions .github/workflows/build-and-test.yml
Original file line number Diff line number Diff line change
Expand Up @@ -234,6 +234,8 @@ jobs:
# on macOS: https://go.dev/doc/go1.15
#- goos: darwin
# goarch: 386
- goos: aix
goarch: ppc64
- goos: darwin
goarch: amd64
- goos: darwin
Expand Down
2 changes: 1 addition & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -179,7 +179,7 @@ Here is a list of community roles with current and previous members:
- [Antoine Toulme](https://github.com/atoulme), Splunk
- [Daniel Jaglowski](https://github.com/djaglowski), observIQ
- [Evan Bradley](https://github.com/evan-bradley), Dynatrace
- [Juraci Paixão Kröhling](https://github.com/jpkrohling), Grafana Labs
- [Juraci Paixão Kröhling](https://github.com/jpkrohling), OllyGarden
- [Tyler Helmuth](https://github.com/TylerHelmuth), Honeycomb
- [Yang Song](https://github.com/songy23), Datadog

Expand Down
2 changes: 1 addition & 1 deletion cmd/builder/go.mod
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,7 @@ require (
go.uber.org/goleak v1.3.0
go.uber.org/multierr v1.11.0
go.uber.org/zap v1.27.0
golang.org/x/mod v0.22.0
golang.org/x/mod v0.23.0
)

require (
Expand Down
4 changes: 2 additions & 2 deletions cmd/builder/go.sum

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

2 changes: 1 addition & 1 deletion cmd/otelcorecol/go.mod
Original file line number Diff line number Diff line change
Expand Up @@ -31,7 +31,7 @@ require (
go.opentelemetry.io/collector/receiver v0.119.0
go.opentelemetry.io/collector/receiver/nopreceiver v0.119.0
go.opentelemetry.io/collector/receiver/otlpreceiver v0.119.0
golang.org/x/sys v0.29.0
golang.org/x/sys v0.30.0
)

require (
Expand Down
4 changes: 2 additions & 2 deletions cmd/otelcorecol/go.sum

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

56 changes: 28 additions & 28 deletions docs/coding-guidelines.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@ for coding advice). The code must adhere to the following robustness principles
are important for software that runs autonomously and continuously without direct
interaction with a human (such as this Collector).

### Naming convention
## Naming convention

To keep naming patterns consistent across the project, naming patterns are enforced to make intent clear by:

Expand Down Expand Up @@ -38,7 +38,7 @@ To keep naming patterns consistent across the project, naming patterns are enfor
- `func CreateTracesExport(...) {...}`
- `func CreateTracesToTracesFunc(...) {...}`

#### Configuration structs
### Configuration structs

When naming configuration structs, use the following guidelines:

Expand All @@ -47,7 +47,7 @@ When naming configuration structs, use the following guidelines:
- Use the `Settings` suffix for configuration structs that are set by developers in the code. For example, `component.TelemetrySettings` ends in `Settings` since it is set by developers in the code.
- Avoid redundant prefixes that are already implied by the package name. For example, use`configgrpc.ClientConfig` instead of `configgrpc.GRPCClientConfig`.

### Module organization
## Module organization

As usual in Go projects, organize your code into packages grouping related functionality. To ensure
that we can evolve different parts of the API independently, you should also group related packages
Expand Down Expand Up @@ -82,7 +82,7 @@ When adding a new module remember to update the following:
1. Open a follow up PR to update pseudo-versions in all go.mod files. See [this example
PR](https://github.com/open-telemetry/opentelemetry-collector/pull/11668).

### Enumerations
## Enumerations

To keep naming patterns consistent across the project, enumeration patterns are enforced to make intent clear:

Expand All @@ -96,7 +96,7 @@ To keep naming patterns consistent across the project, enumeration patterns are
- `pmetric.MetricTypeGauge` for `pmetric.MetricType`


### Recommended Libraries / Defaults
## Recommended Libraries / Defaults

In order to simplify development within the project, we have made certain library recommendations that should be followed.

Expand All @@ -108,13 +108,13 @@ In order to simplify development within the project, we have made certain librar

Within the project, there are some packages that have yet to follow the recommendations and are being addressed. However, any new code should adhere to the recommendations.

### Default Configuration
## Default Configuration

To guarantee backward-compatible behavior, all configuration packages should supply a `NewDefault[config name]` functions that create a default version of the config. The package does not need to guarantee that `NewDefault[config name]` returns a usable configuration—only that default values will be set. For example, if the configuration requires that a field, such as `Endpoint` be set, but there is no valid default value, then `NewDefault[config name]` may set that value to `""` with the expectation that the user will set a valid value.

Users should always initialize the config struct with this function and overwrite anything as needed.

### Startup Error Handling
## Startup Error Handling

Verify configuration during startup and fail fast if the configuration is invalid.
This will bring the attention of a human to the problem as it is more typical for humans
Expand All @@ -126,15 +126,15 @@ explain the problem and exit with a non-zero code. It is acceptable to crash the
during startup if there is no good way to exit cleanly but do your best to log and
exit cleanly with a process exit code.

### Propagate Errors to the Caller
## Propagate Errors to the Caller

Do not crash or exit outside the `main()` function, e.g. via `log.Fatal` or `os.Exit`,
even during startup. Instead, return detailed errors to be handled appropriately
by the caller. The code in packages other than `main` may be imported and used by
third-party applications, and they should have full control over error handling
and process termination.

### Do not Crash after Startup
## Do not Crash after Startup

Do not crash or exit the Collector process after the startup sequence is finished.
A running Collector typically contains data that is received but not yet exported further
Expand All @@ -143,7 +143,7 @@ process will result in losing this data since typically the receiver has
already acknowledged the receipt for this data and the senders of the data will
not send that data again.

### Bad Input Handling
## Bad Input Handling

Do not crash on bad input in receivers or elsewhere in the pipeline.
[Crash-only software](https://en.wikipedia.org/wiki/Crash-only_software)
Expand All @@ -160,7 +160,7 @@ sender. If it is elsewhere in the pipeline it may be too late to send a response
to the sender (particularly in processors which are not synchronously processing
data). In either case, it is recommended to keep a metric that counts bad input data.

### Error Handling and Retries
## Error Handling and Retries

Be rigorous in error handling. Don't ignore errors. Think carefully about each
error and decide if it is a fatal problem or a transient problem that may go away
Expand All @@ -173,7 +173,7 @@ your destination when the network is restored or the destination is recovered.
[Exponential Backoff](https://github.com/cenkalti/backoff) is a good library that
provides all this functionality.

### Logging
## Logging

Log your component startup and shutdown, including successful outcomes (but don't
overdo it, and keep the number of success messages to a minimum).
Expand All @@ -190,7 +190,7 @@ the event happens.
Make log messages human readable and also include data that is needed for easier
understanding of what happened and in what context.

### Executing External Processes
## Executing External Processes

The components should avoid executing arbitrary external processes with arbitrary command
line arguments based on user input, including input received from the network or input
Expand All @@ -208,7 +208,7 @@ The following limitations are recommended:
if necessary, deriving the value from the user input. Limit as much as possible the
size of the possible space of values for command line arguments.

### Observability
## Observability

Out of the box, your users should be able to observe the state of your
component. See [observability.md](observability.md) for more details.
Expand Down Expand Up @@ -293,7 +293,7 @@ builder:
tsp.telemetry.ProcessorTailsamplingSamplingdecisionLatency.Record(ctx, ...)
```

### Resource Usage
## Resource Usage

Limit usage of CPU, RAM, and other resources that the code can use. Do not write code
that consumes resources in an uncontrolled manner. For example, if you have a queue
Expand All @@ -310,7 +310,7 @@ runs out of memory. Instead have protections for these situations, e.g. when hit
resource limits drop the data and record the fact that it was dropped in a metric
that is exposed to users.

### Graceful Shutdown
## Graceful Shutdown

Collector does not yet support graceful shutdown but we plan to add it. All components
must be ready to shutdown gracefully via `Shutdown()` function that all component
Expand All @@ -319,14 +319,14 @@ and export it out of the Collector before shutdown is completed. The shutdown pr
will have a maximum allowed duration so put a limit on how long your shutdown
operation can take.

### Unit Tests
## Unit Tests

Cover important functionality with unit tests. We require that contributions
do not decrease the overall code coverage of the codebase - this is aligned with our
goal to increase coverage over time. Keep track of execution time for your unit
tests and try to keep them as short as possible.

#### Testing Library Recommendations
### Testing Library Recommendations

To keep testing practices consistent across the project, it is advised to use these libraries under
these circumstances:
Expand All @@ -336,12 +336,12 @@ these circumstances:
- For mocking external resources, use `"github.com/stretchr/testify/mock"`
- For validating HTTP traffic interactions, `"net/http/httptest"`

### Integration Testing
## Integration Testing

Integration testing is encouraged throughout the project, container images can be used in order to facilitate
a local version. In their absence, it is strongly advised to mock the integration.

### Using CGO
## Using CGO

Using CGO is prohibited due to the lack of portability and complexity
that comes with managing external libraries with different operating systems and configurations.
Expand All @@ -350,7 +350,7 @@ with clear instructions on how to install the required libraries.
Furthermore, if your package requires CGO, it MUST be able to compile and operate in a no-op mode
or report a warning back to the collector with a clear error saying CGO is required to work.

### Breaking changes
## Breaking changes

Whenever possible, we adhere to [semver](https://semver.org/) as our minimum standards. Even before v1, we strive not to break compatibility
without a good reason. Hence, when a change is known to cause a breaking change, it MUST be clearly marked in the
Expand All @@ -377,7 +377,7 @@ package test
func DoFoo() {}
```

#### End-user impacting changes
### End-user impacting changes

When deprecating a feature affecting end-users, consider first deprecating the feature in one version, then hiding it
behind a [feature
Expand All @@ -389,15 +389,15 @@ that each of the following steps is done in a separate version:
1. Change the feature gate to disable the feature by default, deprecating the gate at the same time
1. Remove the feature and the gate

#### Example #1 - Renaming a function
### Example #1 - Renaming a function

1. Current version `v0.N` has `func GetFoo() Bar`
1. We now decided that `GetBar` is a better name. As such, on `v0.N+1` we add a new `func GetBar() Bar` function,
changing the existing `func GetFoo() Bar` to be an alias of the new function. Additionally, a log entry with a
warning is added to the old function, along with an entry to the changelog.
1. On `v0.N+2`, we MAY remove `func GetFoo() Bar`.

#### Example #2 - Changing the return values of a function
### Example #2 - Changing the return values of a function

1. Current version `v0.N` has `func GetFoo() Foo`
1. We now need to also return an error. We do it by creating a new function that will be equivalent to the existing one
Expand All @@ -406,7 +406,7 @@ that each of the following steps is done in a separate version:
entry with a warning.
1. On `v0.N+2`, we change `func GetFoo() Foo` to `func GetFoo() (Foo, error)`.

#### Example #3 - Changing the arguments of a function
### Example #3 - Changing the arguments of a function

1. Current version `v0.N` has `func GetFoo() Foo`
2. We now decide to do something that might be blocking as part of `func GetFoo() Foo`, so, we start accepting a
Expand All @@ -416,7 +416,7 @@ that each of the following steps is done in a separate version:
3. On `v0.N+2`, we change `func GetFoo() Foo` to `func GetFoo(context.Context) Foo` if desired or remove it entirely if
needed.

#### Exceptions
### Exceptions

For changes to modules that do not have a version of `v1` or higher, we may skip the deprecation process described above
for the following situations. Note that these changes should still be recorded as breaking changes in the changelog.
Expand All @@ -429,11 +429,11 @@ for the following situations. Note that these changes should still be recorded a
breaking change. For this reason, the deprecation process should only be skipped when it is not expected that
the function is commonly passed as a value.

#### Configuration changes
### Configuration changes

See [docs/component-stability.md](component-stability.md) for more information on how to handle configuration changes.

### Specification Tracking
## Specification Tracking

The [OpenTelemetry Specification](https://github.com/open-telemetry/opentelemetry-specification) can be a rapidly
moving target at times. While it may seem efficient to get an early start on implementing new features or
Expand Down
2 changes: 1 addition & 1 deletion exporter/debugexporter/go.mod
Original file line number Diff line number Diff line change
Expand Up @@ -18,7 +18,7 @@ require (
go.opentelemetry.io/collector/pdata/testdata v0.119.0
go.uber.org/goleak v1.3.0
go.uber.org/zap v1.27.0
golang.org/x/sys v0.29.0
golang.org/x/sys v0.30.0
)

require (
Expand Down
4 changes: 2 additions & 2 deletions exporter/debugexporter/go.sum

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

2 changes: 1 addition & 1 deletion otelcol/go.mod
Original file line number Diff line number Diff line change
Expand Up @@ -27,7 +27,7 @@ require (
go.uber.org/multierr v1.11.0
go.uber.org/zap v1.27.0
golang.org/x/exp v0.0.0-20240506185415-9bf2ced13842
golang.org/x/sys v0.29.0
golang.org/x/sys v0.30.0
google.golang.org/grpc v1.70.0
gopkg.in/yaml.v3 v3.0.1
)
Expand Down
4 changes: 2 additions & 2 deletions otelcol/go.sum

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

2 changes: 1 addition & 1 deletion otelcol/otelcoltest/go.mod
Original file line number Diff line number Diff line change
Expand Up @@ -110,7 +110,7 @@ require (
go.uber.org/zap v1.27.0 // indirect
golang.org/x/exp v0.0.0-20240506185415-9bf2ced13842 // indirect
golang.org/x/net v0.34.0 // indirect
golang.org/x/sys v0.29.0 // indirect
golang.org/x/sys v0.30.0 // indirect
golang.org/x/text v0.21.0 // indirect
gonum.org/v1/gonum v0.15.1 // indirect
google.golang.org/genproto/googleapis/api v0.0.0-20250115164207-1a7da9e5054f // indirect
Expand Down
4 changes: 2 additions & 2 deletions otelcol/otelcoltest/go.sum

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

0 comments on commit 72f29d1

Please sign in to comment.