Open Agent Management Protocol (OpAMP) Go Implementation

The StartSettings struct is used with the Start() method to launch a standalone OpAMP Server. It embeds the base Settings and adds network-specific configurations.

• ListenEndpoint: The network address to listen on (e.g., "127.0.0.1:4320").
• ListenPath: The URL path for OpAMP connections. Defaults to "/v1/opamp" if empty.
• TLSConfig: Pointer to a tls.Config for secure connections.
• HTTPMiddleware: An optional function to wrap the http.Handler. For WebSockets, this is called upon connection; for standard HTTP, it is called for every request.

server.StartSettings{
    Settings: server.Settings{
        EnableCompression: true,
    },
    ListenEndpoint: "127.0.0.1:4320",
    ListenPath:     "/v1/opamp",
    TLSConfig:      &tls.Config{ /* ... */ },
    HTTPMiddleware: func(next http.Handler) http.Handler {
        return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
            // custom middleware logic
            next.ServeHTTP(w, r)
        })
    },
}

The Settings struct defines the operational parameters for an OpAMP Server. Use it to configure callbacks, message size limits, and custom capabilities.

• Callbacks: types.Callbacks that the server triggers after successful Attach/Start.
• EnableCompression: Set to true to enable compression for both directions. For WebSockets, this requires client support.
• MaxMessageSize: The maximum size in bytes for transport messages.
  • 0: Defaults to 64 MiB.
  • < 0: No limit applied.
  • For HTTP: Applies to the complete request/response body (pre-compression/post-decompression).
  • For WebSocket: Applies to the complete OpAMP WebSocket message including headers and data.
• CustomCapabilities: A slice of strings representing custom capabilities. Each should be a reverse FQDN with optional version information to uniquely identify the capability, matching those specified in a CustomMessage.

server.Settings{
    EnableCompression: true,
    MaxMessageSize:    1024 * 1024 * 10, // 10 MiB
    CustomCapabilities: []string{"example.com/my-capability/v1"},
}

The example agent can be configured using command-line flags or environment variables. Below is the complete list of available configuration options:

Usage of agent:
  -endpoint string
    	OpAMP server endpoint URL (env var: AGENT_ENDPOINT). (default "wss://127.0.0.1:4320/v1/opamp")
  -heartbeat duration
    	Heartbeat duration (env var: AGENT_HEARTBEAT). (default 30s)
  -quite-agent
    	Disable agent logger (env var: AGENT_QUIET).
  -scale-count uint
    	The number of agents to start in scale mode (env var: AGENT_SCALE_COUNT). (default 1)
  -t string
    	Agent Type String (env var: AGENT_TYPE). (default "io.opentelemetry.collector")
  -tls-ca_file string
    	Path to the CA cert. It verifies the server certificate (env var: AGENT_TLS_CA_FILE).
  -tls-cert_file string
    	Path to the TLS cert (env var: AGENT_TLS_CERT_FILE).
  -tls-insecure
    	Disable the client transport security (env var: AGENT_TLS_INSECURE).
  -tls-insecure_skip_verify
    	Will enable TLS but not verify the certificate (env var: AGENT_TLS_INSECURE_SKIP_VERIFY).
  -tls-key_file string
    	Path to the TLS key (env var: AGENT_TLS_KEY_FILE).
  -v string
    	Agent Version String (env var: AGENT_VERSION). (default "1.0.0")

The OpAMPClient interface is the primary entry point for agents to interact with an OpAMP Server. It allows agents to report their status, health, and available components, while also enabling them to receive remote configurations and send custom messages.

Lifecycle Management:

1. Setup: Call SetAgentDescription() and optionally SetCustomCapabilities(), SetFlags(), or SetAvailableComponents() before calling Start() to ensure these attributes are included in the initial connection handshake.
2. Execution: Call Start(ctx, settings) to begin connection attempts. Start returns immediately and does not block until a connection is established. Connection success or failure is communicated via callbacks (e.g., OnConnectFailed, OnRemoteConfig).
3. Runtime: Use methods like SetHealth(), SetRemoteConfigStatus(), or SendCustomMessage() to update the server on the agent's state or perform actions during the session.
4. Teardown: Call Stop(ctx) to gracefully shut down the client. This ensures no further callbacks are triggered and waits for in-flight callbacks to complete.

// Example conceptual usage of OpAMPClient
var client OpAMPClient

// 1. Configure agent identity before starting
err := client.SetAgentDescription(&protobufs.AgentDescription{...})

// 2. Start the client
err = client.Start(ctx, settings)
if err != nil {
    // Handle immediate errors (e.g. invalid serverURL)
}

// 3. Update status during runtime
client.SetHealth(&protobufs.ComponentHealth{...})

// 4. Stop the client
client.Stop(ctx)

These methods define what the agent is capable of and what it can configure.

• SetCapabilities(capabilities *protobufs.AgentCapabilities) error: Updates the set of capabilities the client supports. Can be called anytime. Must not be nil.
• SetCustomCapabilities(customCapabilities *protobufs.CustomCapabilities) error: Modifies the set of custom capabilities. If called before Start(), they are sent during the initial handshake. Each capability should be a reverse FQDN.
• SetAvailableComponents(components *protobufs.AvailableComponents) error: Modifies the set of components available for configuration.
  • If ReportsAvailableComponents capability is set in StartSettings, this must be called before Start().
  • If called after Start(), components must not be nil and components.Hash must be non-empty.
• SetFlags(flags protobufs.AgentToServerFlags): Modifies the set of flags supported by the client.

If you want to manage your own http.Server instance instead of letting the OpAMP library start its own, use the Attach() method. This returns an HTTPHandlerFunc and a ConnContext that you must integrate into your server.

1. Call Attach(settings).
2. Register the returned HTTPHandlerFunc to your router/mux.
3. Assign the returned ConnContext to the ConnContext field of your http.Server (this is specifically used for plain HTTP connections).
4. Start your http.Server.

// 1. Attach the server
handler, connContext, err := opampServer.Attach(server.Settings{
    EnableCompression: true,
})
if err != nil {
    log.Fatal(err)
}

// 2. Register the handler
mux := http.NewServeMux()
mux.HandleFunc("/opamp", handler)

// 3. Configure and start your own http.Server
httpSrv := &http.Server{
    Addr:         "127.0.0.1:4320",
    Handler:      mux,
    ConnContext:  connContext,
}

if err := httpSrv.ListenAndServe(); err != nil {
    log.Fatal(err)
}

The Start and Stop methods manage the lifecycle of the OpAMP connection.

• Start(ctx context.Context, settings types.StartSettings) error:

  • Initiates connection attempts to the Server.
  • It is non-blocking; it returns before the connection is actually established.
  • Requirement: SetAgentDescription() MUST be called before Start().
  • Guarantees: If Start returns without error, the client will eventually trigger one of OnConnectFailed, OnError, or OnRemoteConfig (unless Stop is called first).
  • Constraint: Should be called only once and not concurrently with other methods.

• Stop(ctx context.Context) error:

  • Gracefully shuts down the client.
  • Requirement: May only be called after Start() has returned successfully.
  • Guarantees: Once Stop returns, no further callbacks will be triggered. It waits for in-flight callbacks to finish, so ensure your callbacks react to context cancellation and do not block indefinitely.

// Start signature
Start(ctx context.Context, settings types.StartSettings) error

// Stop signature
Stop(ctx context.Context) error

Use these methods to communicate the agent's current state to the OpAMP Server. Most of these can be called before or after Start() and are typically used within OnMessage handlers.

• SetAgentDescription(descr *protobufs.AgentDescription) error: Sets attributes of the Agent. Must not be nil. If called after Start(), attributes are included in the next status report.
• AgentDescription() *protobufs.AgentDescription: Returns the last successfully set description.
• SetHealth(health *protobufs.ComponentHealth) error: Sets the health status. Must not be nil.
• UpdateEffectiveConfig(ctx context.Context) error: Fetches the current local effective configuration (via the GetEffectiveConfig callback) and sends it to the Server.
• SetRemoteConfigStatus(status *protobufs.RemoteConfigStatus) error: Reports the current remote configuration status. LastRemoteConfigHash must be non-nil.
• SetPackageStatuses(statuses *protobufs.PackageStatuses) error: Reports current package statuses. ServerProvidedAllPackagesHash must be non-nil.