Document use of NewSchemaless vs NewWithAttributes

[dmathieu]

This issue is an extraction of the discussion in #4846.

We should provide a documentation of the usage of resource.NewSchemaless vs resource.NewWithAttributes, the pros and cons of both approaches and ways to use both efficiently.

[Sanket-0510]

@pellared shall I take this?

[dmathieu]

This is currently assigned to me, but feel free to take it.

[Sanket-0510]

RIght now I can only figure out that users can use resource.NewSchemaless instead of resource.NewWIthAttributes if they want to lower the chances of facing resource merge conflicts while implementing Otel go into their go application using https://opentelemetry.io/docs/languages/go/getting-started/#initialize-the-opentelemetry-sdk

so right now I have only one reason yo use NewSchemaless. where can I find more info regarding both in order to create clear pros and cons of using them in doc file?

[pellared]

The main use case of using resource.NewSchemaless is when the attributes do not even follow the semantic conventions (when one adds custom attributes).

[Sanket-0510]

@pellared I have prepared this thing for now :

Pros:
Lower Chances of Merge Conflicts:

Pro: Using newSchemaless may reduce the likelihood of facing resource merge conflicts,
especially when dealing with a large codebase or when different contributors are adding custom attributes.
Custom Attributes without Semantic Conventions:

Pro: Ideal for scenarios where custom attributes are added without adhering strictly to semantic conventions.


Cons:
Less Semantic Structure:

1. Con: "Schemaless" nature hampers adherence to predefined structures, making code maintenance challenging.

2. Con: Lack of a well-defined schema results in inconsistency in attribute usage across the codebase.

so this pr should be for -Otel-go Docs Right?

Where do I add this?

[dmathieu]

I'm taking a new look at this, and now that we return the merged, schemaless resource on a merge conflict (https://github.com/open-telemetry/opentelemetry-go/pull/4876), I'm not sure adding a more explicit documentation is required.

[pellared]

I agree especially that https://pkg.go.dev/go.opentelemetry.io/otel/sdk/resource#example-New even shows how one can handle the conflict