When should config properties include the word experimental?

[trask]

Using find-all-config-properties.sh --

Config properties with the word experimental:

• otel.instrumentation.apache-shenyu.experimental-span-attributes
• otel.instrumentation.aws-sdk.experimental-record-individual-http-error
• otel.instrumentation.aws-sdk.experimental-span-attributes
• otel.instrumentation.aws-sdk.experimental-use-propagator-for-messaging
• otel.instrumentation.camel.experimental-span-attributes
• otel.instrumentation.common.experimental.controller-telemetry.enabled
• otel.instrumentation.common.experimental.view-telemetry.enabled
• otel.instrumentation.couchbase.experimental-span-attributes
• otel.instrumentation.elasticsearch.experimental-span-attributes
• otel.instrumentation.experimental.span-suppression-strategy
• otel.instrumentation.grpc.experimental-span-attributes
• otel.instrumentation.guava.experimental-span-attributes
• otel.instrumentation.hibernate.experimental-span-attributes
• otel.instrumentation.http.client.emit-experimental-telemetry
• otel.instrumentation.http.client.experimental.redact-query-parameters
• otel.instrumentation.http.server.emit-experimental-telemetry
• otel.instrumentation.hystrix.experimental-span-attributes
• otel.instrumentation.java-util-logging.experimental-log-attributes
• otel.instrumentation.jaxrs.experimental-span-attributes
• otel.instrumentation.jboss-logmanager.experimental-log-attributes
• otel.instrumentation.jboss-logmanager.experimental.capture-mdc-attributes
• otel.instrumentation.jsp.experimental-span-attributes
• otel.instrumentation.kafka.experimental-span-attributes
• otel.instrumentation.kafka.experimental-span-attributes=true
• otel.instrumentation.kubernetes-client.experimental-span-attributes
• otel.instrumentation.lettuce.experimental-span-attributes
• otel.instrumentation.log4j-appender.experimental-log-attributes
• otel.instrumentation.log4j-appender.experimental.capture-code-attributes
• otel.instrumentation.log4j-appender.experimental.capture-map-message-attributes
• otel.instrumentation.log4j-appender.experimental.capture-marker-attribute
• otel.instrumentation.log4j-appender.experimental.capture-mdc-attributes
• otel.instrumentation.logback-appender.experimental-log-attributes
• otel.instrumentation.logback-appender.experimental.capture-arguments
• otel.instrumentation.logback-appender.experimental.capture-code-attributes
• otel.instrumentation.logback-appender.experimental.capture-key-value-pair-attributes
• otel.instrumentation.logback-appender.experimental.capture-logger-context-attributes
• otel.instrumentation.logback-appender.experimental.capture-logstash-attributes
• otel.instrumentation.logback-appender.experimental.capture-marker-attribute
• otel.instrumentation.logback-appender.experimental.capture-mdc-attributes
• otel.instrumentation.messaging.experimental.capture-headers
• otel.instrumentation.messaging.experimental.receive-telemetry.enabled
• otel.instrumentation.oshi.experimental-metrics.enabled
• otel.instrumentation.powerjob.experimental-span-attributes
• otel.instrumentation.pulsar.experimental-span-attributes
• otel.instrumentation.quartz.experimental-span-attributes
• otel.instrumentation.rabbitmq.experimental-span-attributes
• otel.instrumentation.reactor.experimental-span-attributes
• otel.instrumentation.rocketmq-client.experimental-span-attributes
• otel.instrumentation.runtime-telemetry.emit-experimental-telemetry
• otel.instrumentation.rxjava.experimental-span-attributes
• otel.instrumentation.servlet.experimental-span-attributes
• otel.instrumentation.servlet.experimental.capture-request-parameters
• otel.instrumentation.spring-batch.experimental-span-attributes
• otel.instrumentation.spring-batch.experimental.chunk.new-trace
• otel.instrumentation.spring-cloud-gateway.experimental-span-attributes
• otel.instrumentation.spring-scheduling.experimental-span-attributes
• otel.instrumentation.spring-webflux.experimental-span-attributes
• otel.instrumentation.spring-webmvc.experimental-span-attributes
• otel.instrumentation.spymemcached.experimental-span-attributes
• otel.instrumentation.twilio.experimental-span-attributes
• otel.instrumentation.xxl-job.experimental-span-attributes

Config properties without the word experimental:

• otel.instrumentation.%s.enabled
• otel.instrumentation.aws-lambda.flush-timeout
• otel.instrumentation.common.db-statement-sanitizer.enabled
• otel.instrumentation.common.default-enabled
• otel.instrumentation.common.enduser.id.enabled
• otel.instrumentation.common.enduser.role.enabled
• otel.instrumentation.common.enduser.scope.enabled
• otel.instrumentation.common.logging.span-id
• otel.instrumentation.common.logging.trace-flags
• otel.instrumentation.common.logging.trace-id
• otel.instrumentation.common.mdc.resource-attributes
• otel.instrumentation.common.peer-service-mapping
• otel.instrumentation.common.string_key
• otel.instrumentation.elasticsearch.capture-search-query
• otel.instrumentation.executors.include
• otel.instrumentation.executors.include-all
• otel.instrumentation.external-annotations.exclude-methods
• otel.instrumentation.external-annotations.include
• otel.instrumentation.graphql.data-fetcher.enabled
• otel.instrumentation.graphql.query-sanitizer.enabled
• otel.instrumentation.graphql.trivial-data-fetcher.enabled
• otel.instrumentation.grpc.capture-metadata.client.request
• otel.instrumentation.grpc.capture-metadata.server.request
• otel.instrumentation.http.client.capture-request-headers
• otel.instrumentation.http.client.capture-response-headers
• otel.instrumentation.http.known-methods
• otel.instrumentation.http.server.capture-request-headers
• otel.instrumentation.http.server.capture-response-headers
• otel.instrumentation.jdbc.statement-sanitizer.enabled
• otel.instrumentation.kafka-clients-metrics.enabled
• otel.instrumentation.kafka.autoconfigure-interceptor
• otel.instrumentation.kafka.metric-reporter.enabled
• otel.instrumentation.kafka.producer-propagation.enabled
• otel.instrumentation.kotlinx-coroutines.check-class
• otel.instrumentation.lettuce.connection-telemetry.enabled
• otel.instrumentation.log4j-context-data.add-baggage
• otel.instrumentation.logback-appender.enabled
• otel.instrumentation.logback-mdc.add-baggage
• otel.instrumentation.logback-mdc.enabled
• otel.instrumentation.methods.include
• otel.instrumentation.micrometer.base-time-unit
• otel.instrumentation.micrometer.histogram-gauges.enabled
• otel.instrumentation.micrometer.prometheus-mode.enabled
• otel.instrumentation.mongo.statement-sanitizer.enabled
• otel.instrumentation.netty.connection-telemetry.enabled
• otel.instrumentation.netty.ssl-telemetry.enabled
• otel.instrumentation.opentelemetry-annotations.exclude-methods
• otel.instrumentation.opentelemetry-instrumentation-annotations.exclude-methods
• otel.instrumentation.oshi.enabled
• otel.instrumentation.r2dbc.statement-sanitizer.enabled
• otel.instrumentation.reactor-netty.connection-telemetry.enabled
• otel.instrumentation.runtime-telemetry-java17.enable-all
• otel.instrumentation.runtime-telemetry-java17.enabled
• otel.instrumentation.runtime-telemetry.enabled
• otel.instrumentation.runtime-telemetry.package-emitter.enabled
• otel.instrumentation.runtime-telemetry.package-emitter.jars-per-second
• otel.instrumentation.spring-batch.item.enabled
• otel.instrumentation.spring-integration.global-channel-interceptor-patterns
• otel.instrumentation.spring-integration.producer.enabled
• otel.instrumentation.spring-security.enduser.role.granted-authority-prefix
• otel.instrumentation.spring-security.enduser.scope.granted-authority-prefix

I know we want the word experimental when we are emitting our own telemetry that we are making up and is not defined anywhere in the semantic convention repository.

We also have this text in https://github.com/open-telemetry/opentelemetry-java-instrumentation/blob/main/VERSIONING.md#compatibility-requirements

the following incompatible changes are allowed in stable artifacts in this repository:

• Changes to configuration properties that contain the word experimental

though I'm not sure this is really needed for non-stable instrumentations since it also says

the following incompatible changes are allowed in stable artifacts in this repository:

• Changes to the telemetry produced by instrumentation

(btw, these really only apply today to the Java agent since other instrumentations are still alpha, and I believe the expectation is that stable instrumentation should have stable telemetry and stable configuration options)