langfuse-rb 0.4.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e356e95702ea99ed80bfc258a3a1dbfa6c71985bb8a31110f26c09e6ac8c8b8d
-  data.tar.gz: 742033eb63885f9a1b33377258c423a25c0fe6af8554965de8fd76b1807d3a93
+  metadata.gz: 3b2a00b43e48c855cee6d5ccf6b12c36641c469182ddb65231323dcc566d01f2
+  data.tar.gz: 21b9bc01d7297bf7130b4530f25e4fffc8a0ac18036a7e6e97562767b2a4657a
 SHA512:
-  metadata.gz: d26c930cf723cbdbd5fdd738fcbae8b2181aca3f340eb0929c3ab2d76720aa3b1f217fe8f71804607f0cac32a3b115b7a625e02cf982d30ceceb1c0c45c0d603
-  data.tar.gz: a4667dc7d5abe11b7facd78c26e406a394696f9d0ca6663a200ad0232adcd7bd45d7d4bf495b2f98c7a7ed23b5f7b62ab7c2ba7b76a606b546859072b98cedec
+  metadata.gz: b121586667150434548323b0734f456f51fb06c21513bb59aaf7d8bbd07b8077ef23bbf2b87f2cac1514f5b220f54cff19175d97c11d19472306367a888aa97f
+  data.tar.gz: 9b5790ee2504681417cb7fa77fc2ebcb3c4e484bcfd512ba04abd6fbad215b609235d4bf109b0481c7855822d0643203873d49754b485aba487f6e85fb84260e

data/CHANGELOG.md

@@ -7,6 +7,14 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.5.0] - 2026-02-09
+
+### Added
+- Trace listing and retrieval endpoints (`list_traces`, `get_trace`) (#47)
+
+### Documentation
+- Improved documentation readability and formatting (#46)
+
 ## [0.4.0] - 2026-02-08
 
 ### Added
@@ -54,7 +62,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Migrated from legacy ingestion API to OTLP endpoint
 - Removed `tracing_enabled` configuration flag (#2)
 
-[Unreleased]: https://github.com/simplepractice/langfuse-rb/compare/v0.4.0...HEAD
+[Unreleased]: https://github.com/simplepractice/langfuse-rb/compare/v0.5.0...HEAD
+[0.5.0]: https://github.com/simplepractice/langfuse-rb/compare/v0.4.0...v0.5.0
 [0.4.0]: https://github.com/simplepractice/langfuse-rb/compare/v0.3.0...v0.4.0
 [0.3.0]: https://github.com/simplepractice/langfuse-rb/compare/v0.2.0...v0.3.0
 [0.2.0]: https://github.com/simplepractice/langfuse-rb/compare/v0.1.0...v0.2.0

data/lib/langfuse/api_client.rb

@@ -285,6 +285,85 @@ module Langfuse
       cache.shutdown if cache.respond_to?(:shutdown)
     end
 
+    # List traces in the project
+    #
+    # @param page [Integer, nil] Optional page number for pagination
+    # @param limit [Integer, nil] Optional limit per page
+    # @param user_id [String, nil] Filter by user ID
+    # @param name [String, nil] Filter by trace name
+    # @param session_id [String, nil] Filter by session ID
+    # @param from_timestamp [Time, nil] Filter traces after this time
+    # @param to_timestamp [Time, nil] Filter traces before this time
+    # @param order_by [String, nil] Order by field
+    # @param tags [Array<String>, nil] Filter by tags
+    # @param version [String, nil] Filter by version
+    # @param release [String, nil] Filter by release
+    # @param environment [String, nil] Filter by environment
+    # @param fields [String, nil] Comma-separated field groups to include (e.g. "core,scores,metrics")
+    # @param filter [String, nil] JSON string for advanced filtering
+    # @return [Array<Hash>] Array of trace hashes
+    # @raise [UnauthorizedError] if authentication fails
+    # @raise [ApiError] for other API errors
+    #
+    # @example
+    #   traces = api_client.list_traces(page: 1, limit: 10, name: "my-trace")
+    # rubocop:disable Metrics/ParameterLists
+    def list_traces(page: nil, limit: nil, user_id: nil, name: nil, session_id: nil,
+                    from_timestamp: nil, to_timestamp: nil, order_by: nil,
+                    tags: nil, version: nil, release: nil, environment: nil,
+                    fields: nil, filter: nil)
+      result = list_traces_paginated(
+        page: page, limit: limit, user_id: user_id, name: name,
+        session_id: session_id, from_timestamp: from_timestamp,
+        to_timestamp: to_timestamp, order_by: order_by, tags: tags,
+        version: version, release: release, environment: environment,
+        fields: fields, filter: filter
+      )
+      result["data"] || []
+    end
+    # rubocop:enable Metrics/ParameterLists
+
+    # Full paginated response including "meta" for internal pagination use
+    #
+    # @api private
+    # @return [Hash] Full response hash with "data" array and "meta" pagination info
+    # rubocop:disable Metrics/ParameterLists
+    def list_traces_paginated(page: nil, limit: nil, user_id: nil, name: nil, session_id: nil,
+                              from_timestamp: nil, to_timestamp: nil, order_by: nil,
+                              tags: nil, version: nil, release: nil, environment: nil,
+                              fields: nil, filter: nil)
+      with_faraday_error_handling do
+        params = build_traces_params(
+          page: page, limit: limit, user_id: user_id, name: name,
+          session_id: session_id, from_timestamp: from_timestamp,
+          to_timestamp: to_timestamp, order_by: order_by, tags: tags,
+          version: version, release: release, environment: environment,
+          fields: fields, filter: filter
+        )
+        response = connection.get("/api/public/traces", params)
+        handle_response(response)
+      end
+    end
+    # rubocop:enable Metrics/ParameterLists
+
+    # Fetch a trace by ID
+    #
+    # @param id [String] Trace ID
+    # @return [Hash] The trace data
+    # @raise [NotFoundError] if the trace is not found
+    # @raise [UnauthorizedError] if authentication fails
+    # @raise [ApiError] for other API errors
+    #
+    # @example
+    #   trace = api_client.get_trace("trace-uuid-123")
+    def get_trace(id)
+      with_faraday_error_handling do
+        encoded_id = URI.encode_uri_component(id)
+        response = connection.get("/api/public/traces/#{encoded_id}")
+        handle_response(response)
+      end
+    end
+
     # List all datasets in the project
     #
     # @param page [Integer, nil] Optional page number for pagination
@@ -525,6 +604,23 @@ module Langfuse
       }.compact
     end
 
+    # Build query params for list_traces, mapping snake_case to camelCase
+    # rubocop:disable Metrics/ParameterLists
+    def build_traces_params(page:, limit:, user_id:, name:, session_id:,
+                            from_timestamp:, to_timestamp:, order_by:,
+                            tags:, version:, release:, environment:, fields:, filter:)
+      {
+        page: page, limit: limit, userId: user_id, name: name,
+        sessionId: session_id,
+        fromTimestamp: from_timestamp&.iso8601,
+        toTimestamp: to_timestamp&.iso8601,
+        orderBy: order_by, tags: tags, version: version,
+        release: release, environment: environment, fields: fields,
+        filter: filter
+      }.compact
+    end
+    # rubocop:enable Metrics/ParameterLists
+
     # Fetch with SWR cache
     def fetch_with_swr_cache(cache_key, name, version, label)
       cache.fetch_with_stale_while_revalidate(cache_key) do

data/lib/langfuse/client.rb

@@ -439,6 +439,35 @@ module Langfuse
       api_client.list_datasets(page: page, limit: limit)
     end
 
+    # List traces in the project
+    #
+    # @param page [Integer, nil] Optional page number for pagination
+    # @param limit [Integer, nil] Optional limit per page
+    # @param filters [Hash] Additional filters (user_id, name, session_id, etc.)
+    # @return [Array<Hash>] Array of trace hashes
+    # @raise [UnauthorizedError] if authentication fails
+    # @raise [ApiError] for other API errors
+    #
+    # @example
+    #   traces = client.list_traces(page: 1, limit: 10, name: "my-trace")
+    def list_traces(page: nil, limit: nil, **filters)
+      api_client.list_traces(page: page, limit: limit, **filters)
+    end
+
+    # Fetch a trace by ID
+    #
+    # @param id [String] Trace ID
+    # @return [Hash] The trace data
+    # @raise [NotFoundError] if the trace is not found
+    # @raise [UnauthorizedError] if authentication fails
+    # @raise [ApiError] for other API errors
+    #
+    # @example
+    #   trace = client.get_trace("trace-uuid-123")
+    def get_trace(id)
+      api_client.get_trace(id)
+    end
+
     # Create a new dataset item
     #
     # @param dataset_name [String] Name of the dataset to add item to (required)

data/lib/langfuse/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Langfuse
-  VERSION = "0.4.0"
+  VERSION = "0.5.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: langfuse-rb
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.5.0
 platform: ruby
 authors:
 - SimplePractice